Scripted REST Inbound — Complete Setup (Dev + Admin)

Fixes common errors:
- The following mandatory fields are not filled in: Default ACLs
- Application = Global (wrong) → must be HR Leave scope
- API namespace shows 2065034 instead of x_786686_hr_leave

الأسلوب: عربية + إنجليزية تكمّلان بعضهما — بدون ترجمة حرفية لأسماء الشاشات.
Test after setup: REST API Explorer ($restapi.do) — see rest_api_explorer.md

Phase 0 — Switch to scoped application (DO THIS FIRST)

If Application shows Global on the form, you are in the wrong context. — إذا كان Application = Global فأنت خارج تطبيق الإجازات — هذا سبب namespace خاطئ.

Steps

1. Top-right Application picker (or Studio).
2. Select: HR Leave (scope x_786686_hr_leave).

3. Verify:
   Navigate: All > System Applications > Applications — Open direct
   Open HR Leave → Scope = x_786686_hr_leave

4. Optional — create from Studio (recommended):
   - URL: /now/studio
   - Open app HR Leave
   - Create Application File → Scripted REST API — بعد التبديل، عند إنشاء Scripted REST يجب أن ترى Application = HR Leave وليس Global.

Phase 1 — Admin: Role + Integration user (before API form)

1.1 Create integration role

Navigate:
All > User Administration > Roles → New — Open direct

Submit. — هذا الدور يُستخدم في Default ACLs ليسمح لنظام HR الخارجي بالاستدعاء.

1.2 Create integration user

Navigate:
All > User Administration > Users → New — Open direct

Roles (Related list → Edit):

Submit.

1.3 System property (optional but professional)

Navigate:
All > System Properties → New (scope HR Leave) — Open direct

Phase 2 — Admin: Default ACLs (fixes your red error)

Default ACLs is mandatory on Scripted REST Service. You must attach at least one ACL before Submit. — حقل Default ACLs إلزامي — بدون ACL لن يقبل Submit (كما في صورتك).

Method A — Create ACL from the lock icon (recommended on New form)

1. Open Scripted REST New form (after Phase 0 — app = HR Leave).
2. Fill Name and API ID first (see Phase 3 table).
3. Go to tab Security.
4. Find Default ACLs (red asterisk).
5. Click the lock icon (or +) next to Default ACLs → New ACL record opens.

Fill the new ACL:

For lab testing add second ACL or add role admin on same ACL so your admin user can test in Explorer.

6. Save ACL → return to Scripted REST form.
7. Default ACLs list collector → add the ACL you created.
8. Now Submit works.

Method B — Create ACL manually first, then attach

Navigate:
All > System Security > Access Control (ACL) → New — Open direct

Submit.

Then on Scripted REST New → Security → Default ACLs → magnifier → select this ACL.

Method C — Path-based ACL (public API pattern)

Use when you need per-method control (GET vs POST).

Navigate:
All > System Security > Access Control (ACL) → New — Open direct

Attach to Default ACLs the same way.

Phase 3 — Dev: Scripted REST Service (every field)

Navigate (scoped app HR Leave selected):
All > System Web Services > Scripted REST APIs → New — Open direct

Tab: General / top section

Wrong vs right (your screenshot issue):

Tab: Security

Blue info boxes on form:
- Default ACLs apply to all resources unless resource has its own ACLs.
- For public APIs use path-based ACLs — we use role-based for HRIS.

Submit the Scripted REST Service record.

Phase 4 — Dev: Resource (endpoint) — every field

Open saved API → Related list Resources → New

Resource script prerequisites

Before testing, confirm these exist in scope HR Leave:

Submit Resource.

Final URL:
https://.service-now.com/api/x_786686_hr_leave/hrlx_api_v2/leave

Phase 5 — Admin: Table ACL for integration insert

REST ACL allows calling the API. Table ACL allows inserting the leave row. — ACL الـ REST ≠ ACL الجدول — تحتاج الاثنين.

Update ACL 3 (create on leave request)

File: src/security/acls.md

On ACL create for x_786686_hr_leave_req_v2, script should allow integration role:

answer = gs.hasRole('x_786686_hr_leave.employee')
 || gs.hasRole('x_786686_hr_leave.hr_admin')
 || gs.hasRole('x_786686_hr_leave.integration');

Or add Requires role (multi):
x_786686_hr_leave.employee,x_786686_hr_leave.integration

Test with Impersonate:
All > User Administration > Impersonate User → hrlx.integration → try create record on form. — Open direct

Phase 6 — Test in REST API Explorer

Navigate:
All > System Web Services > REST API Explorer — Open direct
URL: $restapi.do

Request body:

{
 "employee_id": "EMP001",
 "leave_type": "annual",
 "start_date": "2026-06-01",
 "end_date": "2026-06-05",
 "reason": "Vacation"
}

Click Send.

Verify record:
x_786686_hr_leave_req_v2.list

Impersonate test:
1. Impersonate hrlx.integration
2. Repeat Send in Explorer (or Postman with Basic Auth)

Phase 7 — Sample data for professional practice

7.1 Employee (required for employee_id lookup)

Table: x_786686_hr_leave_employee_v2

7.2 Leave types / state (choices)

Checklist — copy before go-live

• [ ] Application picker = HR Leave (not Global)
• [ ] API namespace = x_786686_hr_leave
• [ ] Default ACLs populated (mandatory)
• [ ] Role x_786686_hr_leave.integration exists
• [ ] User hrlx.integration has rest_service + integration role
• [ ] Resource POST /leave + script pasted
• [ ] Script Include HRLXProIntegrationUtilsV2 active
• [ ] Employee EMP001 exists
• [ ] Table ACL allows integration insert
• [ ] Explorer Send returns 201
• [ ] Copy as cURL documented for HRIS team

Related files