Create Bundle

Creates a bundle of service appointments manually. This resource accepts service appointment IDs and a manual bundling policy ID. The manual bundling policy specifies the bundling rules and has to be marked for manual bundling. This resource returns the ID of the bundle service appointment. This API is not supported in Gov Cloud. This endpoint is available in version 54.0 and later of the Salesforce API.

Add a Remote Site 

  1. From Setup, in the Quick Find box, enter Security, and then select Remote Site Settings.

  2. Click New Remote Site.

  3. Enter a name.

  4. For Remote Site URL, enter https://api.salesforce.com/

  5. Save your changes.

Syntax 

URI: HOST/bundleflow/api/v1.0/bundle

Where HOST is a variable.

Format: JSON

HTTP Method: POST

Authentication: Authorization: Bearer TOKEN

Where TOKEN is a variable.

If the authentication token isn’t valid, a 401 HTTP status is returned.

Headers:

  • request.setHeader('x-sfdc-tenant-id', 'core/prod/ORG-ID_18_Characters');—Field Service functional domain
  • sf_api_version—Salesforce API version. Minimum version is 53.0.
  • Authorization—Authorization token.
  • Content-Type—File format. Valid value is JSON.
  • Referer—Org domain URL.

Request Body 

The request body contains these properties.

FieldTypeDescription
userStringOptional. User name of user sending the request.
initiateStringType of bundle request. Valid value: manual.
bundlePolicyIdStringID of the related bundle policy containing the bundling rules.
saRequestPayloadsArrayDetails of service appointments that are bundled.
serviceAppointmentIdStringID of service appointments to be bundled.
actionStringBundling action performed on this service appointment. Valid value: add.

Example 

This example shows a manual bundle request of two service appointments.

1{
2    "user": "Misha1",
3    "initiate": "manual",
4    "bundlePolicyId": "7sTx00000000006EAA",
5    "saRequestPayloads": [
6        {
7            "serviceAppointmentId": "08px000000NzbmsAAB",
8            "action": "add"
9        },
10        {
11            "serviceAppointmentId": "08pT300000006LLIAY",
12            "action": "add"
13        }
14    ]
15}

Response Body 

The response body contains these properties.

FieldTypeDescription
bundleIdStringID of the new bundle. If the bundle isn’t created, this field is null.
responsePayloadsArrayDetails of the bundled objects.
objectNameStringType of object. Output: ServiceAppointment.
objectIdStringID of the service appointment.
actionStringAction performed on the object.
statusStringSpecifies if this object is bundled correctly. Output: SUCCESS or FAIL.
messageCodeNumberSuccess or error code of bundling the service appointment. 0 means success. The error codes are listed in Error Responses.
messageStringSuccess or error message of bundling the object.
statusStringStatus of the request. Output: SUCCESS or FAIL.
messageCodeNumberSuccess or error code of the request. 0 means success. The error codes are listed in Error Responses.
messageStringSuccess or error message of the request.
messageAdditionalInfoStringMore information provided by Salesforce.

Example: Successful Response 

This example shows the output of two service appointments bundled successfully.

1{
2  "bundleId": "08px000000NzdH8AAJ",
3  "responsePayloads": [
4    {
5      "objectName": "ServiceAppointment",
6      "objectId": "08px000000NzbmsAAB",
7      "action": "add",
8      "status": "SUCCESS",
9      "messageCode": "NONE",
10      "message": "Success",
11      "messageParams": [
12
13      ]
14    },
15    {
16      "objectName": "ServiceAppointment",
17      "objectId": "08pT300000006LLIAY",
18      "action": "add",
19      "status": "SUCCESS",
20      "messageCode": "NONE",
21      "message": "Success",
22      "messageParams": [
23
24      ]
25    }
26  ],
27  "status": "SUCCESS",
28  "messageCode": "NONE",
29  "message": "Success"
30}

Example: Fail Response 

This example shows the output of a request that’s trying to bundle a service appointment that’s already a bundle service appointment. A service appointment can’t be part of two bundles, so the response status is FAIL.

1{
2   "bundleId":null,
3   "responsePayloads":[
4      {
5         "objectName":"ServiceAppointment",
6         "objectId":"08px000000NzdH8AAJ",
7         "action":"add",
8         "status":"FAIL",
9         "messageCode":"SA_ALREADY_BUNDLED",
10         "message":"Is already a bundle service appointment.",
11         "messageParams":[
12
13         ]
14      }
15   ],
16   "status":"FAIL",
17   "messageCode":"ERROR_CREATING_BUNDLE",
18   "message":"We couldn't bundle the service appointment.",
19   "messageAdditionalInfo": ""
20}

Error Responses 

CodeNameMessage
0NONE<Service Appointment ID#>: Success.
1UNSUPPORTED_VERSIONAsk your admin to check the API version, then try again.
2SA_PAYLOAD_SHOULD_CONTAIN_ADD_ACTIONS_ONLYCreate bundles using add actions only.
3EMPTY_BUNDLE_POLICYEnter an ID for the bundlePolicyId.
4EMPTY_BUNDLE_INITIATESpecify manual or auto for the initiate entry.
5EMPTY_BUNDLE_SERVICE_APPOINTMENTAdd a bundle service appointment.
6SA_PAYLOAD_DUPLICATED_SASRemove duplicate service appointment IDs.
7SA_IS_BUNDLE<Service Appointment ID#>: Is already a bundle service appointment.
8SA_ALREADY_BUNDLED<Service Appointment ID#>: Is a bundle member service appointment in another bundle.
9STATUS_FORBIDDEN<Service Appointment ID#>: Can’t be bundled in the current status.
10SA_PAYLOAD_SHOULD_NOT_CONTAIN_MIX_ACTIONSSend separate requests for add and remove actions.
11SA_IS_NOT_BUNDLESelect a bundle service appointment and try again.
12EXCEEDED_BUNDLE_MEMBERS_LIMITYou reached the maximum number of service appointments for this bundle. Remove some of them and try again.
13SA_PAYLOAD_SHOULD_CONTAIN_ONLY_BUNDLE_MEMBERSTo remove bundle members from a bundle, include only service appointments that are bundle members.
14ERROR_IN_BASIC_VALIDATIONSWe couldn’t bundle the service appointments.
15ERROR_IN_LIMIT_VALIDATIONSN/A
16ERROR_IN_CRITERIA_VALIDATIONSN/A
17ERROR_IN_SERVICE_TERRITORY_VALIDATIONSConfirm or revise the service territories of the selected service appointments. Or ask your admin for help.
18ERROR_IN_RESTRICTION_VALIDATIONSConfirm or revise the selected service appointments. Or ask your admin to check the restriction policies.
19EXCEEDED_BUNDLE_DURATION_LIMITN/A
20EMPTY_BODYFill in the request.
21SA_IS_NOT_BUNDLED<Service Appointment ID#>: Can’t remove a service appointment that isn’t in the bundle.
22ERROR_IN_AGGREGATIONConfirm or revise the selected service appointments. Or ask your admin to check the aggregation policies.
23ERROR_IN_PROPAGATIONConfirm or revise the selected service appointments. Or ask your admin to check the propagation policies.
24GET_POLICY_FAILUREAsk your admin to check the bundle policies, then try again.
25GET_CONFIG_FAILUREAsk your admin to check the bundle config, then try again.
26GET_BUNDLE_INFO_FAILURETry again later.
27ERROR_IN_LOGICWe couldn’t bundle the service appointments.
28EMPTY_BUNDLE_MEMBERSAdd bundle member service appointments.
29EMPTY_BUNDLE_PARENT_WORK_ORDER_IDAdd the work order ID for the bundle service appointment.
30UNBUNDLE_REQUEST_ASSIGNED_RESOURCES_NOT_COMPATiBLETo unbundle a scheduled bundle, send assigned resources for each service appointment.
31EMPTY_OLD_VALUESTo update a bundle, send the current values.
32EMPTY_NEW_VALUESTo update a bundle, send the new values.
33SA_PAYLOAD_SHOULD_CONTAIN_AT_LEAST_ONE_ADD_OR_REMOVE_ACTIONTo update a bundle, send at least one add or remove action.
34FORBIDDEN_FIELDS_IN_POLICY_OBJECTConfirm or revise the selected service appointments. Or ask your admin to check the field names selected in the related policies.
35EMPTY_SERVICE_TERRITORYAdd a Service Territory ID.
36EMPTY_START_TIMEAdd the interval’s start time.
37EMPTY_END_TIMEAdd the interval’s end time.
38ERROR_IN_BUNDLE_POLICY_RFCConfirm or revise the selected service appointments. Or ask your admin to check the recordset filter criteria in the bundle policy.
39ERROR_IN_TIME_ZONE_VALIDATIONSelect service appointments that are in the same time zone. Or ask your admin for help.
40ERROR_IN_LOGIC_UNBUNDLEWe couldn’t unbundle the service appointment.
41ERROR_CREATING_BUNDLEWe couldn’t bundle the service appointments.
42ERROR_ADDING_TO_BUNDLEWe couldn’t add the service appointment to the bundle.
43ERROR_REMOVING_FROM_BUNDLEWe couldn’t remove the service appointment from the bundle.
44ERROR_UNBUNDLINGWe couldn’t unbundle the service appointment.
58ERROR_IN_MSW_VALIDATIONSWe can’t bundle service appointments with dependencies. Remove the dependencies and try again.
-500http errorHmm… Something went wrong. Try again.

Code Sample from Apex 

1public static Map<String, String> createSABundle() {
2    String apiVersion = '54.0'; // Spring '22
3    String bundleApi = '/bundleflow/api/v1.0/bundle';
4    String host = {Namespace}.BundleLogic.getBundlerFalconEnvironment();
5    String ref = URL.getOrgDomainUrl().toExternalForm();
6
7    String bundleService = host + bundleApi;
8
9    // Create HTTP request
10    HttpRequest request = new HttpRequest();
11    request.setEndpoint(bundleService);
12    request.setMethod('POST');
13    request.setHeader('sf_api_version', apiVersion);
14    request.setHeader('Content-Type', 'application/json' );
15    // NOTE: This user must have 'Field Service Integration' permissions.
16    request.setHeader('Authorization', 'Bearer ' + UserInfo.getSessionId());
17    request.setHeader('Referer', ref);
18    request.setHeader('x-sfdc-tenant-id', 'core/prod/ORG-ID_18_Characters');
19    request.setTimeout(120000);
20
21    // Create the body
22    Map<String, Object> body = new Map<String, Object>();
23    body.put('initiate','manual');
24    body.put('bundlePolicyId','7sT9A0000004DX6UAM'); // NOTE: Use a real bundle policy ID.
25
26    Map<String, Object> saList = new Map<String, Object>();
27    saList.put('serviceAppointmentId', '08p9A0000005LEGQA2'); // NOTE: Use a real Service Appointment ID.
28    saList.put('action', 'add');
29
30    List<Object> objectsList =  new List<Object>();
31    objectsList.add(saList);
32
33    body.put('saRequestPayloads', objectsList);
34
35    String reqBody = JSON.serialize(body);
36    System.debug(body);
37    request.setBody(reqBody);
38
39    HttpResponse response = new Http().send(request);
40
41    // Parse the JSON response
42
43    // Handle a redirect message
44    while (response.getStatusCode() == 302) {
45        request.setEndpoint(response.getHeader('Location'));
46        response = new Http().send(request);
47    }
48
49    Map<String, String> returnValue = new Map<String, String>();
50    returnValue.put('statusCode', String.valueOf(response.getStatusCode()));
51
52    // Return value when we don't get a success response
53    if (response.getStatusCode() != 200) {
54        returnValue.put('message', 'The status code returned was not expected: ' + response.getStatusCode() + ' ' + response.getStatus());
55        System.debug(returnValue.get('message'));
56        return (returnValue);
57
58    // Return value when we do get a success response
59    } else {
60        returnValue.put('message', response.getBody());
61        System.debug(response.getBody());
62        return (returnValue);
63    }
64}
65
66Map<String, String> response = createSABundle();
67System.debug(response);