TVR-33624 : [API] Cascading Request - API reference documentation

src/api-reference/request/v4.endpoints.participant-resources.markdown

@@ -0,0 +1,165 @@
+---
+title: Travel Request v4 - Participant Resources
+layout: reference
+---
+# Travel Request v4 - Participant Resources
+
+Manage participants and child requests attached to a Budget Request.
+
+## <a name="get-request-participants"></a>Get participants for a Budget Request
+
+This endpoint will enable to retrieve the list of participants of a Budget Request, as well as the child Requests for each of the participants.
+
+### Scopes
+
+`travelrequest.write` - Refer to [Scope Usage](./v4.get-started.html#scope-usage) for full details.
+
+### HTTP Request
+
+##### URI Template
+
+```
+GET {datacenter}/travelrequest/v4/requests/{requestUuid}/participants
+```
+
+#### Parameters
+
+Name|Type|Format|Description
+---|---|---|---
+`requestUuid`|`string`|[RFC 4122]|**Required** The unique identifier of the Request.
+`userId`|`string`|-|The unique identifier of the user getting the participants list. If empty when using a Company token the default system user will be assumed to perform the action.
+
+#### Headers
+
+`concur-correlationid` is a specific custom header used for technical support in the form of a [RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace](https://tools.ietf.org/html/rfc4122).
+
+#### Payload
+
+None.
+
+### HTTP Response
+
+#### HTTP Status Codes
+
+To learn more about response HTTP status codes for this API see [Travel Request v4 - HTTP Status Codes](./v4.response-codes.html).
+
+#### Payload
+
+[ParentRequestParticipant](./v4.endpoints.schemas.html#schema-parentrequestparticipant)
+
+### Example - One participant with two Child Requests and One participant without Child Request
+
+#### HTTP Request
+
+```shell
+GET https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/participants
+Accept: application/json
+Authorization: Bearer {token}
+Concur-CorrelationId: 5512c7be-3fab-4d65-ae69-8a74a04a0c7f
+```
+
+#### HTTP Response
+
+```shell
+200 OK
+```
+
+```json
+[
+  {
+    "participant": {
+      "id": "60dea1fd-489f-48b9-925f-0d62a5b48175"
+    },
+    "requests": [
+      {
+        "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4",
+        "id": "A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4",
+        "template": "https://us.api.concursolutions.com/travelrequest/v4/requests/{id}"
+      },
+      {
+        "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5",
+        "id": "B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5",
+        "template": "https://us.api.concursolutions.com/travelrequest/v4/requests/{id}"
+      },
+    ]
+  },
+  {
+    "participant": {
+      "id": "72efb2ae-5a0e-59ca-b037-1e73b6c59286"
+    }
+  }
+]
+```
+
+## <a name="patch-request-participants"></a>Manage participants of a budget request
+
+This endpoint will enable to manage participants (add or remove them) from a Budget Request.
+
+### Scopes
+
+`travelrequest.write` - Refer to [Scope Usage](./v4.get-started.html#scope-usage) for full details.
+
+### HTTP Request
+
+##### URI Template
+
+```
+PATCH {datacenter}/travelrequest/v4/requests/{requestUuid}/participants
+```
+
+#### Parameters
+
+Name|Type|Format|Description
+---|---|---|---
+`requestUuid`|`string`|[RFC 4122]|**Required** The unique identifier of the Request.
+`userId`|`string`|-|The unique identifier of the user updating the participants list. **Required** when connecting with a Company token. If empty, a 400 `missingRequiredParam` error.
+
+#### Headers
+
+`concur-correlationid` is a specific custom header used for technical support in the form of a [RFC 4122 A Universally Unique IDentifier (UUID) URN Namespace](https://tools.ietf.org/html/rfc4122).
+
+#### Payload
+
+[Request Participants For Patch](./v4.endpoints.schemas.html#schema-requestparticipantsforpatch)
+
+### HTTP Response
+
+#### HTTP Status Codes
+
+To learn more about response HTTP status codes for this API see [Travel Request v4 - HTTP Status Codes](./v4.response-codes.html).
+
+#### Payload
+
+None.
+
+### Example - adding and removing a participant to a Budget Request
+
+#### HTTP Request
+
+```shell
+PATCH https://us.api.concursolutions.com/travelrequest/v4/requests/224AF3CDCC2A5244A37C72FA5770C6F2/participants
+Content-Type: application/merge-patch+json
+Accept: application/json
+Authorization: Bearer {token}
+Concur-CorrelationId: 5512c7be-3fab-4d65-ae69-8a74a04a0c7f
+```
+
+```json
+{
+  "value": [
+    {
+      "id": "8422A66-A9B0-1424-5802-0D9BCD4351D3"
+    },
+    {
+      "id": "9C33FBA0-ACB7-4F85-83BD-FC0DF3A78522",
+      "@deleted": true
+    }
+  ]
+}
+```
+
+#### HTTP Response
+
+```shell
+204 No Content
+```

src/api-reference/request/v4.endpoints.policy-resources.markdown

@@ -63,14 +63,22 @@ Concur-CorrelationId: 5512c7be-3fab-4d65-ae69-8a74a04a0c7f
 ```json
 [
   {
-    "href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/F4C8BD31CA9D4D6292795BE687EB9B2A",
-    "id": "F4C8BD31CA9D4D6292795BE687EB9B2A",
-   "name": "Internal training Request policy"
+   "href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/F4C8BD31CA9D4D6292795BE687EB9B2A",
+   "id": "F4C8BD31CA9D4D6292795BE687EB9B2A",
+   "name": "Internal training Request policy",
+   "allowParticipants": false
   },
   {
-    "href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/F10E6059B5A14A4C80327FE387491026",
-    "id": "F10E6059B5A14A4C80327FE387491026",
-   "name": "Client meeting Request policy"
+   "href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/F10E6059B5A14A4C80327FE387491026",
+   "id": "F10E6059B5A14A4C80327FE387491026",
+   "name": "Client meeting Request policy",
+   "allowParticipants": false,
+  },
+  {
+   "href": "https://us.api.concursolutions.com/travelrequest/v4/userpolicies/98B49B2523DDAB41A182DD581C637415",
+   "id": "98B49B2523DDAB41A182DD581C637415",
+   "name": "Budget Event Request policy",
+   "allowParticipants": true
   }
 ]
 

src/api-reference/request/v4.endpoints.schemas.markdown

@@ -32,13 +32,16 @@ Name|Type|Format|Description
 `highestExceptionLevel`|`string`|-|The highest level of exception contained in this Request. Supported values: `WARNING`, `ERROR`, and `NONE`
 `href`|`string`|[RFC 3986]|Hyperlink to the resource for this Request.
 `id`|`string`|-|The unique identifier of the Request.
+`isParentRequest`|`boolean`|-|Indicates whether this Request is a Budget Request.
 `lastModified`|`timestamp`|[RFC 3339] `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`|The date the Request was last modified.
 `mainDestination`|`object`|[`Location`](#location)|The main destination of the Request.
 `name`|`string`|-|The name of the Request.
 `owner`|`object`|[`Employee`](#schema-employee)|The employee who owns the Request.
 `pendingApproval`|`boolean`|-|Indicates whether this Request is pending approval.
 `pnr`|`string`|-|The value of the pnr provided within the agency proposals by the travel agency.
 `policy`|`object`|[`ResourceLink`](#schema-resourcelink)|The policy that applies to the Request.
+`parentRequestId`|`string`|-|Required if a Child Request is created, corresponds to the unique identifier of the Budget Request the Child Request will be linked to.
+`parentRequest`|`object`|[`ResourceLink`](#schema-resourcelink)|If the Request is a Child Request, reference to the corresponding Budget Request.
 `requestId`|`string`|4 to 6 alphanumeric characters|The public key of the Request (unique per customer).
 `startDate`|`date`|[ISO 8601] `yyyy-MM-dd`|The start date of the Request.
 `startTime`|`time`|`HH:mm`|The start time of the Request.
@@ -236,6 +239,27 @@ Name|Type|Format|Description
 `href`|`string`|[RFC 3986]|Hyperlink to the resource for this Request policy.
 `id`|`string`|-|The Request policy unique identifier.
 `name`|`string`|-|The name of the Request policy.
+`allowParticipants`|`boolean`|-|Whether this policy can add participants (policy is a Budget Request).
+
+## <a name="schema-parentrequestparticipant"></a>Budget Request Participant
+
+Name|Type|Format|Description
+---|---|---|---
+`participant`|`object`|[`ResourceLink`](#schema-resourcelink)|The list of participants of the Budget Request.
+`requests`|`array`|[`ResourceLink`](#schema-resourcelink)|The list of Child Requests from the participant associated to the Budget Request.
+
+## <a name="schema-requestparticipantsforpatch"></a>Request Participants For Patch
+
+Name|Type|Format|Description
+---|---|---|---
+`value`|`array`|[`Request Participant For Patch`](#schema-requestparticipantforpatch)|The list of participants to be added or removed from the Budget Request.
+
+## <a name="schema-requestparticipantforpatch"></a>Request Participant For Patch
+
+Name|Type|Format|Description
+---|---|---|---
+`id`|`string`|[RFC 4122]|**Required** The participant unique identifier.
+`@deleted`|`boolean`|-|Whether the participant should be added or deleted from the Budget Request. If false or not provided then the participant is added.
 
 ## <a name="schema-requesttype"></a>Request Type
 

src/api-reference/request/v4.response-codes.markdown

@@ -8,6 +8,7 @@ HTTP Status Code|Response Body|Description
 ---|---|---
 200 OK|-|Your GET request succeeded.
 201 Created|-|Your POST request succeeded.
+204 No Content|-|Your PATCH request succeeded.
 400 Bad Request|`badParam` the request has bad parameter(s) {requestName}|The name of the request doesn't have the expected format
 -|`invalidJson` invalid json structure|An input JSON structure couldn't be parsed
 -|`invalidDate` error while parsing date value {dateValue}|A date or datetime value couldn't be parsed