# Sap Successfactors

> >

- **Type:** Skill
- **Install:** `agentstack add skill-efeumutaslan-sap-skills-sap-successfactors`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [efeumutaslan](https://agentstack.voostack.com/s/efeumutaslan)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [efeumutaslan](https://github.com/efeumutaslan)
- **Source:** https://github.com/efeumutaslan/SAP-SKILLS/tree/main/skills/sap-successfactors

## Install

```sh
agentstack add skill-efeumutaslan-sap-skills-sap-successfactors
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# SAP SuccessFactors HXM Development

## Related Skills
- `sap-security-authorization` — XSUAA/IAS for BTP-side extensions
- `sap-s4hana-extensibility` — Hybrid HR/Finance integration scenarios
- `sap-integration-suite-advanced` — Pre-built SF iFlows and API Management
- `sap-event-mesh` — SF Intelligent Services events to BTP Event Mesh
- `sap-cap-advanced` — CAP-based BTP extensions consuming SF APIs

## Quick Start

**Choose your development approach:**

| Scenario | Approach | API |
|----------|----------|-----|
| Read/write employee data | OData V2 API | `/odata/v2/` endpoints |
| Custom business objects | MDF (Metadata Framework) | MDF OData API |
| Event-driven extension | Intelligent Services | Event triggers → BTP |
| Analytics / reporting | People Analytics OData | `$metadata` reporting |
| UI extension | Extension Center | Custom UI on SF pages |
| Integration | SAP Integration Suite | Pre-built iFlows |

**Minimal API call — Get employee by ID:**

```http
GET https:///odata/v2/User('EMPL001')
  ?$select=userId,firstName,lastName,email,department
  &$format=json
Authorization: Bearer 
```

## Core Concepts

### API Architecture
- **OData V2**: Primary API protocol for all SuccessFactors entities
- **Entity sets**: Map to business objects (User, EmpJob, EmpEmployment, PerPersonal, etc.)
- **Compound Employee API**: Single request for employee + all related entities
- **Associations**: Navigate between entities (`User('ID')/directReports`)
- **Effective dating**: Most HR entities have `startDate`/`endDate` for temporal data

### Metadata Framework (MDF)
- **Generic Objects (GOs)**: Custom business objects defined via MDF
- **Rules engine**: Business rules attached to MDF objects (onInit, onSave, onChange)
- **Picklists**: Reusable value lists for dropdowns
- **Association types**: 1:1, 1:N, configurable navigation
- **MDF OData**: Auto-generated OData endpoints for custom MDF objects

### Permission Model (RBP)
- **Role-Based Permissions (RBP)**: Foundation of SF security
- **Permission roles**: Group of permission grants assigned to users
- **Target population**: Which employees a role can access (granting rules)
- **Permission groups**: Logical grouping of entities and fields
- **Field-level permissions**: Control read/write/hidden per field per role

### Integration Patterns
| Pattern | Tool | When |
|---------|------|------|
| Real-time sync | SAP Integration Suite iFlows | Employee master → S/4HANA |
| Event-driven | Intelligent Services → BTP | React to HR events |
| Batch extract | OData `$filter` with paging | Nightly data sync |
| UI mashup | Extension Center / BTP HTML5 | Embed custom UI in SF |

## Common Patterns

### Pattern 1: Compound Employee API (Efficient Bulk Read)

```http
GET /odata/v2/CompoundEmployee
  ?$filter=lastModifiedDateTime gt datetime'2026-03-01T00:00:00'
  &$select=person/personIdExternal,
           personalInfo/firstName,personalInfo/lastName,
           jobInfo/company,jobInfo/department,jobInfo/jobTitle,
           employmentInfo/startDate
  &$format=json
  &$top=100
  &$skiptoken=
```

### Pattern 2: Create Custom MDF Object Record

```http
POST /odata/v2/upsert
Content-Type: application/json

{
  "__metadata": {
    "uri": "cust_Equipment('NEW001')"
  },
  "externalCode": "NEW001",
  "cust_name": "MacBook Pro 16",
  "cust_assignedTo": "EMPL001",
  "cust_status": "ASSIGNED",
  "effectiveStartDate": "/Date(1711929600000)/"
}
```

### Pattern 3: Event-Driven Extension (Intelligent Services)

```javascript
// BTP Cloud Foundry / Kyma — handle SF event
const express = require('express');
const app = express();

app.post('/sf-events', (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'HIRE':
      console.log(`New hire: ${event.userId}, start: ${event.startDate}`);
      // Trigger provisioning: AD account, equipment, onboarding tasks
      provisionNewHire(event.userId);
      break;
    case 'TERMINATION':
      console.log(`Termination: ${event.userId}, last day: ${event.endDate}`);
      // Trigger de-provisioning
      deprovisionEmployee(event.userId);
      break;
  }

  res.status(200).json({ status: 'processed' });
});

app.listen(process.env.PORT || 8080);
```

### Pattern 4: OData Batch Request

```http
POST /odata/v2/$batch HTTP/1.1
Content-Type: multipart/mixed; boundary=batch_001

--batch_001
Content-Type: application/http
Content-Transfer-Encoding: binary

GET User?$filter=department eq 'IT'&$select=userId,firstName,lastName&$top=50 HTTP/1.1
Accept: application/json

--batch_001
Content-Type: application/http
Content-Transfer-Encoding: binary

GET EmpJob?$filter=company eq '1010' and startDate ge datetime'2026-01-01T00:00:00'&$top=50 HTTP/1.1
Accept: application/json

--batch_001--
```

### Pattern 5: OAuth2 SAML Bearer Token Flow

```javascript
const axios = require('axios');
const { SignedXml } = require('xml-crypto');

async function getSFToken(userId) {
  // 1. Generate SAML assertion (signed with X.509 cert)
  const samlAssertion = generateSAMLAssertion(userId);

  // 2. Exchange SAML assertion for OAuth2 token
  const tokenResponse = await axios.post(
    'https:///oauth/token',
    new URLSearchParams({
      grant_type: 'urn:ietf:params:oauth:grant-type:saml2-bearer',
      assertion: Buffer.from(samlAssertion).toString('base64'),
      client_id: '',
      company_id: ''
    }),
    { headers: { 'Content-Type': 'application/x-www-form-urlencoded' } }
  );

  return tokenResponse.data.access_token;
}
```

### Pattern 6: People Analytics OData Report

```http
GET /odata/v2/cust_headcountReport
  ?$filter=asOfDate eq datetime'2026-03-24T00:00:00'
  &$select=department,headcount,fte,avgTenure
  &$orderby=department asc
  &$format=json
```

## Error Catalog

| HTTP Status | Error | Root Cause | Fix |
|-------------|-------|------------|-----|
| `401` | `Invalid OAuth token` | Token expired or wrong API server | Refresh token; verify token URL matches API server region |
| `403` | `Insufficient permissions` | RBP role missing for entity/field | Check Admin Center → Manage Permission Roles; add entity permissions |
| `400` | `Invalid effective date` | Date format wrong or future-dated insert blocked | Use `/Date(epoch)/` format; check date restrictions on entity |
| `404` | `Entity not found` | Wrong entity name or entity not enabled | Check `$metadata`; some entities need activation in Provisioning |
| `429` | `Rate limit exceeded` | Too many API calls per minute | Implement exponential backoff; use `$batch` for bulk operations |
| `500` | `Business rule validation failed` | MDF rule rejected the data | Check Manage Business Rules for the object; review rule conditions |

## Performance Tips

1. **Use `$select`** — Always specify needed fields; SF returns ALL fields by default (very slow)
2. **Compound Employee API** — One call vs. 5-10 separate entity calls per employee
3. **`$batch` requests** — Group up to 100 operations in one HTTP call; reduces round-trips
4. **Paging with `$skiptoken`** — Never use `$skip` for large datasets; use server-driven paging
5. **`lastModifiedDateTime` filter** — Delta sync instead of full extract
6. **Cache `$metadata`** — Metadata response is large (>1 MB); cache it, refresh daily
7. **Avoid deep expansions** — `$expand` with 3+ levels causes timeouts; use separate queries
8. **Time zone awareness** — All dates in UTC; convert at display layer, not in API queries

## Gotchas

- **Effective dating**: Every update to EmpJob, EmpEmployment, etc. requires `startDate`; omitting it creates records effective "today" which may conflict with existing records
- **Picklist values**: Use `picklistId` + `optionId`, NOT display text — display text is locale-dependent
- **API server vs. data center**: Token endpoint and API base URL may be different hostnames
- **SAML assertion clock skew**: Assertions must have `NotBefore` / `NotOnOrAfter` within 5 min of server time
- **MDF field limits**: Custom MDF objects max 150 fields; plan field usage carefully
- **Integration Center vs. Suite**: Integration Center (within SF) for simple scenarios; SAP Integration Suite for complex multi-system flows

## Advanced Patterns

### Extension Center — Custom UI Injection

```javascript
// SF Extension Center: inject custom UI into SuccessFactors pages
// Hosted on BTP HTML5 Application Repository
// Registered via Admin Center → Extension Center

// manifest.json (Fiori-style)
{
  "sap.app": {
    "id": "com.company.sf.custom-onboarding",
    "type": "application",
    "applicationVersion": { "version": "1.0.0" }
  },
  "sap.sf.extension": {
    "targetPage": "EmployeeProfile",
    "position": "belowHeader",
    "label": "Custom Onboarding Checklist"
  }
}
```

### Employee Central → S/4HANA Replication

```
SF Employee Central               SAP S/4HANA
     │                                 │
     ├─ Employee master data ─────────►│ Business Partner (BP)
     │  (HCM replication)              │
     ├─ Org structure ────────────────►│ Org Management
     │                                 │
     ├─ Cost center assignment ───────►│ CO cost centers
     │                                 │
     └─ Compensation data ────────────►│ Payroll (optional)
```

**Replication setup:**
1. Enable API Center in SF (Admin Center → Company Settings)
2. Configure Integration Center for employee replication
3. Map SF fields to S/4HANA BP fields
4. Set up delta sync (lastModifiedDateTime filter)

### MDF Business Rules Engine

```
Rule Type: onChange
Object: cust_LeaveRequest
Trigger Field: cust_leaveType

IF cust_leaveType == "ANNUAL"
  THEN SET cust_requiresApproval = TRUE
  AND SET cust_maxDays = 30

IF cust_leaveType == "SICK"
  AND cust_days > 3
  THEN SET cust_requiresMedicalCert = TRUE

IF cust_startDate < TODAY()
  THEN RAISE ERROR "Leave start date cannot be in the past"
```

## Bundled Resources

| File | When to Read |
|------|-------------|
| `references/sf-api-reference.md` | Full SF API entity reference with query patterns |

## Source Documentation

- [SAP SuccessFactors API Reference](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/d599f15995d348a1b45ba5603e2aba9b)
- [SF Extension Center Guide](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM/f8796a3df8204c57b5f7f7c0776cde72)
- [SF OData API Business Rules](https://help.sap.com/docs/SAP_SUCCESSFACTORS_PLATFORM)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [efeumutaslan](https://github.com/efeumutaslan)
- **Source:** [efeumutaslan/SAP-SKILLS](https://github.com/efeumutaslan/SAP-SKILLS)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-efeumutaslan-sap-skills-sap-successfactors
- Seller: https://agentstack.voostack.com/s/efeumutaslan
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.