This page describes the endpoints used to synchronize customers between your system and the interworks.cloud platform. The information on this page focuses on customers using your services and how you can successfully create and manage them in your system.

Account Get Synchronization Options

Swagger documentation: GET /API​/Accounts​/SyncOptions

This endpoint describes the input fields required to create customer records in your system. The interworks.cloud platform uses this to determine the information your system needs to create a customer, other than general customer details such as their name, address, contact details, etc. An example of a synchronization option is the domain prefix required to create a new tenant in the Microsoft system.

TIP: First, check the “Account Synchronize” endpoint to establish the information passed by the interworks.cloud platform by default to identify what you are missing and the essential parts of the account synchronization options.

The synchronization options can be simple numeric, text fields, or lists of values that the customer must complete the first time they purchase one of your services. These options, along with the rest of the information the interworks.cloud platform registers for a customer, will be included in the request body of the “Account Synchronize” endpoint so you can have all the information you require to create the customer in your system.

Username Synchronization Option

Several services are using email as the identifier of a customer. To accommodate this common request, the customer’s email is found automatically. To use this automation, define the username sync option as below:

{
 "ID": "username",
 "Definition": {
 "ID": "username",
 "SortOrder": 0,
 "Name": "Username",
 "Description": null,
 "Kind": "SimpleValue",
 "DataType": "Text",
 "IsRequired": true,
 "PredefinedValues": [],
 "IsReadOnly": false,
 "AvailableToStorefront": false
}

If your endpoint returns a username sync option with the above syntax, our platform will automatically set the account email or primary contact email (if the account email is not found) as the user name.

Define which Synchronization Options must be filled by the Customer

Although the most common scenario is that the customer fills the synchronization options when they place their first order, there might be scenarios where a sync option should not be available to your customers. An example of this may be a field filled automatically by the interworks.cloud platform (like the username field) or a field your partner must fill in using the BSS portal.

To accommodate this scenario, we included the field “AvailableToStorefront” in the definition of a synchronization option. Only the synchronization options set to true will be available to the customer during their first order.

When this Endpoint is called

This endpoint is called every time the settings of your service manager are saved.

Accessing the Synchronization Options in BSS Portal

The synchronization options you have defined are stored as account custom fields. The interworks.cloud platform creates an account custom fields group with the name of your service manager. The synchronization options your endpoint returns are added as custom fields in this category. The account custom fields are located in BSS → Setup → Accounts → Custom Fields.

Refresh the Synchronization Options

If you have introduced new sync options or changed them, execute the following actions to refresh the account synchronization options in the interworks.cloud platform.

• Go to BSS → Setup → Account → Custom Fields and select the group that includes the account sync options for your service manager (the Microsoft Cloud Service EU Region group in our example below).
  

• Select Groups > Delete Group action, as shown below  
  

• Select the first option on the modal appeared and Apply to delete the custom fields group and the custom fields included

• Go to Setup → Administration → System Options → Applications Setup and select Settings for your cloud application.
• Select Save to get a fresh list of synchronization options as provided by your implementation.
• Check in BSS → Setup → Account → Custom Fields that the group now includes the new synchronization options.

Implementation Checklist

If you want to test your implementation, you should check the following:

• Registration of synchronization options as account custom fields. Check that the sync options have been successfully created as account custom fields. Make sure that the field types are those you defined in your implementation.
• Sync Options availability in Account details page. All your sync options must be accessible from the synchronization options pop-up:

• Sync Options availability for a new customer. The “Service Details” step must be part of the checkout process for allowing the customer to fill in the sync options. This step must be presented only once, when the customer places an order for one of your services for the first time, and it must include only the sync options with the flag AvailableToStorefront = true. An example of the ordering process for a new customer can be found at Microsoft Cloud Services – Ordering of a new Customer.

Account Synchronize

Swagger documentation: POST API/Accounts/Synchronize

The purpose of this endpoint is to create an entry for a customer in your system.

Request

The customer information in the request body of the endpoint is the following:

 "ID": "3000",
  "ExternalID": "",
  "ResellerID": "",
  "ResellerExternalID": "",
  "Name": "Direct Customer Example",
  "Code": "DIRECT-Example",
  "Phone": "323-999-4500",
  "Fax": "323-999-5500",
  "WebSite": "https://www.direct.com",
  "Email": "[email protected]",
  "Description": "A direct customer account example",
  

"SyncOptions": {
    "username": "[email protected]",
    "role": "1"
  },

"ContactDetails": {
    "ID": "15200",
    "FirstName": "User",
    "LastName": "Direct Customer",
    "Phone": "323-999-4505",
    "Fax": "323-999-5505",
    "Email": "[email protected]"
  },
  

"Address": {
    "Address1": "123 Main Street",
    "Address2": "Unit 12",
    "City": "Chicago",
    "PostCode": "94903",
    "State": {
      "Code": "CA",
      "Name": "California"
    },
    "Country": {
      "Code": "US",
      "Name": "United States"
    }
  }

ExtraDetails": {}, 

Response

The expected response contains the following fields:

• AccountExtraInfo – The contents of this field are saved and sent as ExtraDetails in every request. Any key-value pairs in AccountExtraInfo can be used as variables in the notification template. For more information, please see the example in the next section.
• Code – The error code. If the value of this field is between -80,000 and -89,999, the error description is shown to the Storefront user. This includes various validation errors which can assist the user in determining the cause of the error. Otherwise, the message shown is “Contact your support department” and only the BSS user can see the error description returned by the service manager.
• Message – A description of the error.
• Result – Contains the ID of the account in the external system. This ExternalID is then sent in every subsequent request.
• SendNotification – When set to true, an email with access instructions (described below) is sent to the customer.

Send Email to Customer with Access Instructions

To send an email to your customer with account activation instructions, or instructions on how to access your management portal, enable Send email notification to customer. This is especially useful if your system does not have this function. Note that SendNotification in the response must be equal to true, otherwise no email will be sent.

1. Check Send email notification to customer
2. Select Save. The system creates the notification template upon saving.
3. Select Edit Template to change the content of the email notification

The default email body for such notifications is the following:

You will notice that this default template includes the following merge fields:

• Contacts.FullName: This is the full name of the contact that belongs to the BSS account that synchronized with your system. Depending on the sychronization flow (e.g. if the synchronization triggered from the customer by placing a new order, or from a user in BSS portal) this can be the name of the user that placed the order in the Storefront or the primary contact of this customer, as defined by the account manager in the BSS portal.
• username: This field returns the value of the username synchronization option. If you are not using such sync option, you should remove it from your email.
• Password: To use this field, return the password you created for the customer in your system in the response body of the Account Synchronize endpoint. You must add the variable GeneratedPassword.
  
  {
  “ErrorCode”: 0,
  “ErrorMessage”: “”,
  “Result”: “customer_3932”,
  “GeneratedPassword”:”{P@ssw0rd}”
  }

Any key-value pairs in AccountExtraInfo can be used as variables in the notification template. E.g., If the response contains “customer_location”: “us” in AccountExtraInfo, it can be used as [#customer_location#] in the notification template.

IMPORTANT: We strongly suggest not sending passwords via email. We only support this approach if you haven’t implemented yet your own activation mechanism for your new customers and you want a temporary solution for sending the access credentials to your customers.

When this Endpoint is called

This endpoint is called when:

• The account is manually synchronized – When you select Save and Synchronize in the Synchronization Options

• During basket checkout – When your customer purchases a service for the first time
• An order is executed in the BSS portal – Also when a customer who purchases a service for the first time

Please refer to the following flow chart(s) to see at which point in the flow the endpoint is called:

• Basket Checkout for Unsynchronized Account
• Account Synchronization in the BSS
• Subscription Creation
• Order Execution in the BSS

Implementation Checklist

To test the endpoint, synchronize an account manually in the BSS, and check that the customer has been created.

Account Delete

Swagger documentation: POST API/Accounts/Delete

The purpose of this endpoint is to delete a customer from your system. It is called when an account is deleted in the BSS portal.

Request

The request contains the following fields:

• ExternalID – The ID of the customer in your system. It is the ID returned from the “Account Synchronize” endpoint.
• ExtraDetails – The purpose of this field is to assist the service manager in finding information in the 3rd party system which, in another case, may have needed additional API calls.

Response

The response contains the following fields:

• Code – The error code. A value of 0 means that no error has occurred.
• Message – A description of the error (if applicable)

When this Endpoint is Called

The endpoint is called when the BSS user deletes an account.

Implementation Checklist

The endpoint can be tested by deleting an account and checking both systems to ensure it has been deleted.

Account Exists

Swagger documentation: POST API/Accounts/Exists

The purpose of this endpoint is to determine whether an account already exists in your system.

Request

The request contains the fields of the Accounts Synchronize request, in addition to the following fields:

• ID – The ID of the account in interworks.cloud platform
• ExternalID – The ID of the customer in your system.
  • If the externalID is not empty, it means that the BSS account is already synchronized with your system and its value will be the ID returned from the Account Synchronize endpoint.
  • If the externalID is empty, it means that the BSS account is not synchronized with your system. In this case you should check whether the account we have in our platform already exists in your system by checking the account synchronization options in the request body. Check please see the section Synchronize a BSS Account with a Customer already exists in your System for more details.

Response

The value of the ErrorCode field in the response shows whether the account exists. If the value of the field is:

• Less than 0, this means that an error has occurred and is specified in the ErrorMessage field.
• Equal to 0 or more than 2, the account does not exist.
• Equal to 1, the account exists, and its ExternalID will be the value of the Result field.
• Equal to 2, the account exists but it not valid. The ErrorMessage field contains the appropriate message.

Synchronize a BSS Account with an Existing Customer in Your System

Our platform allows a BSS account to be synchronized with an existing customer of yours instead of creating a new one. This is achieved by checking the synchronization options of the account:

• If in your system the customers are uniquely identified by their domain, this means that the value of one of the account synchronization options fields will be their domain.
• The account manager creates a new BSS account and sets the domain synchronization to a domain that already belongs to one of your customers.
• When our system will try to synchronize this account, it will first call the Account Exists endpoint before calling the Account Synchronize endpoint.
• The implementation of the Account Exists endpoint should check the synchronization options in the request body of the account, and if the domain option belongs to an existing customer, your response should be the following:
  • ErrorCode = 1 to inform us that the customer exists in your system
  • Results = ID of the customer in your system.
• In case the external system responds with ErrorCode = 1, the Account Synchronize endpoint will not be called. Instead, the BSS Account will be linked with the ExternalID returned in the Results field.

This implementation is useful for cases where the customer is created in your system and the account manager creates it in our platform as well and then links it to the customer record in your system.

When this Endpoint is Called

The endpoint is called when an account is manually synchronized. If the account exists on the external system, then it must return the ExternalID value in the response, which is then linked to the account entry in the BSS. If the ExternalID is returned, Account Synchronize is not called.

Please refer to the following flow chart(s) to see at which point in the flow the endpoint is called:

• Basket Checkout for Unsynchronized Account
• Account Synchronization in the BSS
• Subscription Creation
• Order Execution in the BSS

Implementation Checklist

Check the response of the endpoint when the account has not yet been synchronized for the first time. The endpoint will be called when you select Save & Synchronize in the Sync Options.

Otherwise, you may create a new subscription for a customer who is not synchronized. The endpoint will be called before the provisioning takes place.