Step 3: Create the API
Last updated
Last updated
Once the Entity is created, create an API to generate customer activities records and store them in the Activities Entity created in Step 1.
The API will receive the customer ID as a single value and a list of customer activities (based on the 1 to Many relation configured in Step 2). The items in the list will be defined by the attributes of the fields created in the Entity “UserName_Acc_Activities”.
When all the items in the list are read, the API will create a new record for the Entity “UserName_Acc_Activities”. The API will then update the activity information against the customer ID received.
To go to APIs, click “API” under the “APIs and integration” menu on the left side panel.
To create a new API, click the [+ API] button.
The New API page displays with the Details tab preselected. To define the API, add the following information:
Enter the API name as “UserName_Acc_AddActivities”. The name indicates that a customer activity is added.
Select the API method as “POST”. This defines that the API will be posting or sending data.
Optionally add a description for the API.
Select the Group "UserName".
Add constant text for API Paths as “acc” and “addactivities”. Each of both parameters displays in a blue bubble.
The URL for the API is generated.
Enable “public documentation”. This defines the API documentation to be accessed publicly.
To define the Request body and Response body details, go to the “Inputs & outputs” tab.
To define the Request body, go to the Inputs & outputs tab>Request body section. Click it to expand the already created Request Body. It is defined with the following information:
By default, the name for the request body is “defaultRequestJsonBody”. For this exercise, label it as “ActivityRequestJsonBody”.
Content type from the list of values is selected as “application/json”. This defines the type of content in the request.
Character set is selected as “Universal (UTF-8)”.
Op.”onally enter a description for the “Request Body”. (This is used in the API documentation.)
To define the Json object, enter the following sample json object:
{ "customer_id" : "string: representing the customer GUID",
"activities" : [ { "Activity_Type" : "string: one of the following: Incoming Support call,Email,Product details request,Product Offer email,Outgoing call",
"Activity_Description" : "string: the description text of the activity",
"Activity_DateTime" : "string representing the date time in the form of YYYY-MM-DD hh:mm:ss",
"Activity_Priority" : 0,
"Activity_AssignedTo": "string representing the person this activity is assigned to and if missing sets it to default",
"Activity_CreatedBy" : "string representing the person created this activity and if missing sets it to default" } ] }
This json object indicates the type of request that will be received including the Customer ID and the list of activities for the customer.
The key “activities” has the value enclosed in “[ ]”. This means that this key will have a list of values instead of just one value.
To define the Response body, go to the Inputs & outputs tab>Response body section and click it to expand it. A Response body is already created and defined with the following information:
By default, the name for the response body is “defaultResponseJsonBody”. For this exercise, keep the response body name as is.
The Content type from the list of values is selected as “application/json”. This defines the type of content in the response.
The Response Code is selected as “200 OK”.
Character set is selected as “Universal (UTF-8)”.
Optionally, add a description for the “Response body”. (This is used in the API documentation)
To define a sample Json for the response, type the following json object:
{ "status": "success or failed",
"errorcode": "0",
"message": "The response of creating the entity record.",
"details": [] }
This object indicates that:
- The status is “success” or “failed”.
- The error code is zero (0).
- The message displayed is “The response of creating the entity record”.
- The details will be a list of values as identified by the two square brackets “[]”.
To define the Target Entity for this API, go to the “Target Entities” tab. Target entities are the entities that the Actions in this API can process data into i.e. perform add, update or delete upon. To create a new target entity, click [+ Target entity].
To define the Target Entity for storing the created record:
Select Target Entity as “UserName_Acc_customers”.
Keep “Select a default Validation pipeline” as is. If a Validation pipeline needs to be applied to the data before storing in an entity, the relevant Validation pipeline can be selected in this field. In this exercise, no Validation pipeline is applied.
“Show in API gateway” toggle button is enabled by default. This must be enabled so that the API is visible to the API gateway through which it can process the information into the entity.
To see the default variables created for an API, go to the “Variables” tab. The following two (2) Read Only variables are predefined:
Variable Name: “Request”, Data Type: “WebRequest”. This variable contains the Web Request received.
Variable Name: “Response”, Data Type: “WebResponse”. This variable contains the Web Response sent.
To create Actions for this API, go to the “Code” tab. By default, an “Action box” is already created with the description of the “Action box” as “OnExit”.
Double click the description and label the “Action box” as “add customer activities”.
Expand the “Action box”. In the “Code” tab, an Action called “API Respond” is already added. Notice the variable as “defaultResponseJsonBody”. Remove the existing action “API Respond”. (It will be added later after all the actions are defined as no action is executed after “API Respond” Action.)
To define the variables, go to the “Variables” tab of the “Action box”. To create a new variable, click the [+ Variable] button and create 3 new variables.
Define the variables as follows:
Variable Name: “customeractivity”, Data Type: “UserName_Acc_Activities”. This variable will contain customer activity details for the customer activities entity.
Variable Name: “customer”, Data Type: “UserName_Acc_customers”. This variable will contain customer information from the customer account entity.
Variable Name: “resultofupdate”, Data Type: “JXPResponse”. This variable contains the response to be shown to the user i.e. success or failure of creation of record.
To define the actions for the API, click on the “Code” tab. Add Action by clicking the (+) sign in the “Action box”.
To receive the details (from the json object) for the customer field “Customer_ID” in the Entity “UserName_Acc_customers” (via “Request Body”), define the following Action to first convert it to GUID data type from string and update the variable “customer” as follows:
Select Action as “Update Variable”.
Select the Target variable as “customer.Customer_ID”.
Select Value as Variables>Request>ActivityRequestJsonBody>customer_id>toGUID(). It displays as “Request.ActivityRequestJsonBody.customer_id.toGUID()”.
Add four (4) more “Actions” by clicking the (+) button.
To traverse a list of items received in the Activities list in the Request, update each item to the corresponding field in the record for the Activities entity and update the information for the customer via the “Customer_Activities” relation, define the second Action as follows:
Select Action as “Traverse List”. A list of the activity records will be traversed.
Select “Traverse the List” as Variables>Request>ActivityRequestJsonBody>Activities. It is displayed as “Request.ActivityRequestJsonBody.Activities”.
The “item” is the element in the list to be traversed. It is automatically populated.
To store the values in the “Actions”, in the “Variables” tab of the “Traverse List” Action:
Variable Name: “item”, Data Type: “Json”. This variable is automatically created on selecting “Traverse List” Action.
Add a variable with variable Name: “activity”, Data Type: “UserName_Acc_Activities”. This variable will be updated with the value from the item traversed.
To define “Actions” in the “Traverse List”, go to the "Code" tab and add two (2) Actions by clicking the (+) button.
To take the value of each item received in the Json request (“item”) and update it to a corresponding field for activity record (for “UserName_Acc_Activities entity”), define the first Action in the Traverse List as follows:
Select Action as “Update Entity fields from json”.
Select the Target variable as “activity”.
Select Source variable as “item” (Variables>item).
The second Action in the Traverse List updates the value of the activity variable and updates the variable customer information through the 1 to many relation.
Select Action as “Add item to List”.
Select the Target variable as customer>Customer_Activities. It is displayed as “customer.Customer_Activities”.
Select Source variable as Variables>activity. It is displayed as “activity”.
To add the detail as a record to the target entity, define the third Action after the “Traverse List” in the “Action box” to update the record in the target entity:
Select Action as “Update Entity record on primary key”. This Action updates the record of the Target Entity or related entities based on the primary key.
Select “resultofupdate”. (This variable “resultofupdate” displays success or error messages.)
Select Source as “customer”.
To convert the “resultofupdate” variable to json and store it in the response body, define the fourth Action in the “Action box” as follows:
Select Action as “Update Variable”.
Select the Target variable as Response>defaultResponseJsonBody. It displays as “Response.defaultResponseJsonBody”.
Select Value as Variables>resultofupdate>toJson(). It displays as “resultofupdate.toJson()”.
The fifth and last Action in the “Action box” sends the response to the user.
Select Action as “API Respond”.
Select Response Body as “defaultResponseJsonBody”.
After all the Actions are defined, the “Code” tab should look as per the image below.
To save the API, click the [Save] button.
To publish the API, click the [Publish] button.
To define the API gateway, go to the Details tab and add the API gateway for this API as “UserName_Acc_AddActivities”.
To save the API, click the [Save] button.
In the “Details” tab and on the right-hand side, ensure the API is enabled.
