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

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

@@ -0,0 +1,170 @@
+---
+title: Travel Request v4 - Participant Resources
+layout: reference
+---
+# Travel Request v4 - Participant Resources
+
+## <a name="get-request-participants"></a>Get the list of Participants for a given Request
+
+### 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
+
+List of [Parent Request Participant](./v4.endpoints.schemas.html#schema-parentrequestparticipant)
+
+### Example
+
+#### 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": {
+      "href": "https://us.api.concursolutions.com/profile/v1/users/60dea1fd-489f-48b9-925f-0d62a5b48175",
+      "id": "60dea1fd-489f-48b9-925f-0d62a5b48175",
+      "template": "https://us.api.concursolutions.com/profile/v1/users/{id}"
+    },
+    "requests": [
+      {
+        "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4",
+        "id": "A1B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4",
+        "template": "https://us.api.concursolutions.com/travelrequest/v4/requests/{id}"
+      }
+    ]
+  },
+  {
+    "participant": {
+      "href": "https://us.api.concursolutions.com/profile/v1/users/72efb2ae-5a0e-59ca-b037-1e73b6c59286",
+      "id": "72efb2ae-5a0e-59ca-b037-1e73b6c59286",
+      "template": "https://us.api.concursolutions.com/profile/v1/users/{id}"
+    },
+    "requests": [
+      {
+        "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5",
+        "id": "B2C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5",
+        "template": "https://us.api.concursolutions.com/travelrequest/v4/requests/{id}"
+      },
+      {
+        "href": "https://us.api.concursolutions.com/travelrequest/v4/requests/C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6",
+        "id": "C3D4E5F6A1B2C3D4E5F6A1B2C3D4E5F6",
+        "template": "https://us.api.concursolutions.com/travelrequest/v4/requests/{id}"
+      }
+    ]
+  }
+]
+```
+
+## <a name="patch-request-participants"></a>Manage Participants of a given 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 patching 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
+
+#### 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": "56B8B8A0-99FD-4FA9-8DE9-A57F3EE3C2FD"
+    },
+    {
+      "@deleted": true,
+      "id": "A1B2C3D4-E5F6-A1B2-C3D4-E5F6A1B2C3D4"
+    }
+  ]
+}
+```
+
+#### HTTP Response
+
+```shell
+204 No Content
+```

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

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

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

@@ -29,6 +29,9 @@ Name|Type|Format|Description
 `expenses`|`array`|[`ResourceLink`](#schema-resourcelink)|Expected expenses attached to this Request.
 `extensionOf`|`object`|[`ExtensionOf`](#schema-extensionof)|The Request for which this Request is an extension of, or addendum to.
 `eventRequest`|`object`|[`ResourceLink`](#schema-resourcelink)|The parent Event Request to which this child Request is related.
+`isParentRequest`|`boolean`|-|Indicates whether this Request is of Parent type.
+`parentRequestId`|`string`|-|The short identifier of the parent Request.
+`parentRequest`|`object`|[`ResourceLink`](#schema-resourcelink)|The parent of this Request.
 `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.
@@ -236,6 +239,7 @@ 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 allows to create child requests/allows to add participants.
 
 ## <a name="schema-requesttype"></a>Request Type
 
@@ -510,3 +514,23 @@ Name|Type|Format|Description
 Name|Type|Format|Description
 ---|---|---|---
 `name`|`string`|-|**Required** The name for the booking (e.g. `Ferry`, `Bus`).
+
+## <a name="schema-parentrequestparticipant"></a>Parent Request Participant
+
+Name|Type|Format|Description
+---|---|---|---
+`participant`|`object`|[`ResourceLink`](#schema-resourcelink)|Participant of the parent request.
+`requests`|`array`|[`ResourceLink`](#schema-resourcelink)|Child requests owned by the participant.
+
+## <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 add or delete from the Request.
+
+## <a name="schema-requestparticipantforpatch"></a>Request Participant For Patch
+
+Name|Type|Format|Description
+---|---|---|---
+`@deleted`|`boolean`|-|Whether this Participant should be deleted. If absent or `false`, the Participant will be added.
+`id`|`string`|[RFC 4122]|**Required** The unique identifier of the Participant.

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