Feature Blog on Usability of Output section

[ClarenceWanrap]

Motivation:
This blog focuses on the usability of the Output Section within an Action of the Action Project that can be maintained using the Actions Editor. The Output parameters help to describe and maintain the response structure of the API.

The Actions Project and the Action Editor are generally available from 18th October 2022.

Parent Blog:

Please go through the following blogs written by my colleague, Vivek Vishal, for more information.
Actions Editor – Feature List, Usage and Maintenance of Actions Project

Blog Series

• Part 1 of the Blog Series: Actions Project – Major Changes including the Actions Editor Available No...

• Part 2 of the Blog Series/Parent Blog: Actions Editor – Feature List, Usage and Maintenance of Actio...

Concept & Need:
The Output Section contains a list of http-codes that could be part of a response from an API. Each of these http-codes contain a list of parameters.

When an API responds with a particular http-code, the response would contain the same structure as described by the Action Designer in this Section.

The Action Designer can modify the list of http-codes by Adding/Deleting the code from the Drop Down list. While adding a new http-code, validation is being done.

In the case when no http-codes are found in the schema, a default code is added with the name ‘default’.

The Action Designer can design the response structure for each of these http-codes by modifying these parameters.

Modifications that can be done are as follows:

• Delete Parameters
• Add Parameters
• Modify the Label
• Modify the API Format
• Add/Remove a Tag

A basic use case for this is when an Action Designer wants to trim down the parameters that might not be relevant to the Business Process at hand but which is part of the response from the API. He can achieve this by simply deleting the parameters which are not relevant to him and keeping the ones which are required and specific to his use case.

Example:

• Select Output/Error code to edit using the drop-down as shown below.

Figure 1: Select Output/Error code

Users can then make modifications to the structure of the selected code as follows:

Sort:

Designers can sort across Ascending and Descending order through the parameters which will help them in quick selection of the parameters.

Figure 2: Sorting through the parameters

Search:

Designers can search through the parameters as shown below. This will help them in quick selection of the parameters.

Figure 3: Searching through the parameters

Delete Parameters:

• Select the list of parameters to delete.

Figure 4: Select Parameters.

• Click on the Remove icon present at the top-right corner of table.

Figure 5: Remove Icon

• A dialog Box is displayed with the list of selected parameter.

Figure 6: Remove Parameters Dialog.

• Click on the “Remove” button

• Selected Parameters are soft deleted from the table.
• For permanent deletion, designer can remove them from the side Panel.
• Click on the “Add” button on the top right corner of the table and Select “Field” from the drop down.
• In the side Panel, Select Parameters to permanently delete as shown below.
• Click on Delete Button

Figure 7: Permanently delete fields.

• Save the Project by clicking on the Save button.

Add Parameters:

1. Previously Deleted Fields

• To add back previously  deleted fields, Click on the “Add” icon present at the top-right corner of table and Select the “Field” option from the drop down.

Figure 8: Add Field.

• In the side panel under the Available Fields Tab, Select the parameters to be added.

Figure 9: Add Parameters Dialog.

• Click on the “Add” button.

• Selected parameters are added to the Table.

• Save the Project by clicking on the Save button.

1. New Custom Fields

• To add new custom fields using Side Panel’s Form, Click on the “Add” icon present at the top-right corner of table and Select the “Field” option from the drop down as shown above.
• Click on the “New Field” tab.

Figure 10: Add Parameters using Side Panel.

• Fill the details of the new custom field and Click on Add button.

Figure 11: Add Fields.

• New parameters are added to the Table.

Figure 12: Custom Parameters are added to the table.

• Save the Project by clicking on the Save button.

1. Adding new Fields from Sample JSON

• To add new custom fields using Sample JSON, Click on the “Add” icon present at the top-right corner of table and Select the “Fields from Sample JSON” option from the drop down as shown above.

Figure 13: Adding Fields using Sample JSON

• A wizard with a JSON editor and an Output Preview opens up as shown below.

Figure 14: Wizard with JSON Editor and Preview

• Enter the JSON in the JSON Editor section and Click on “Next” button. Alternatively, the Action designer can upload a JSON file by Clicking on the “Choose File” button.

Figure 15: JSON Editor

• In the Output Preview, the newly added fields are highlighted. Click on “Add” button.

Figure 16: Output Preview

• New parameters are added to the Table

Figure 17: New Fields are added to Table

• Save the Project by clicking on the Save button.

Modification of Output Parameters:

Changing the Label:

• Click on the Label of any particular parameter

Figure 18: Edit Label

• Edit the label accordingly as shown below

Figure 19: Enter Label value.

• Modifed Label is reflected in the table

Figure 20: Modified Label.

Changing the API Format:

Concept & Need:
Please refer to the Blog by my colleague Akshil Verma on API Formats to understand its relevance and functionality.

 Example:

• Click on the API Format of any particular parameter and Select the format from the drop down accordingly as shown below

Figure 21: Select API Format.

Figure 22: API Format Drop Down.

Figure 23: Modified API Format.

Note: Format cannot be added to object, array type parameters and currently Format is enabled only for “string” type parameter. 

Changing Tags:

Concept & Need:
Responses from an API may contain many arrays; it is sometimes necessary to mark a particular array as the Main Output Array. This will help the Citizen Developer consuming the Action in searching through the response received. Similarly,  responses can be tag

Here are the total list of Tags that can be added for output fileds:

• Main Output Array

• $Top

• $Skip

• $At

• PageNo

• PageSize

• $Search

• $From

• $To

Out of these tags only Main Output Array, $At, $From and $To can be used in parameters of Output Section and the remaining in Input Section.

Example:

• Click on the Tags of any particular parameter and Select the Tag from the drop down accordingly as shown below

Figure 24: Select Tags.

Figure 25: Tags Drop Down

Figure 26: Selected Tag

Note: Once a Tag is added for any particular parameter, that same tag cannot be reused for a different parameter i.e. a tag can only be used once.

Save:
Users must Save the changes by pressing the Save button.

Figure 27: Save Button.

A Message Toast with the message “The changes have been saved” is shown on Success

Figure 28: Save Success.

In case there are unsaved changes, an action dialog is shown while navigating to a different action as shown below. Select “Save” to save all new changes and “Discard Changes” to reset the changes.” :

Figure 29: Unsaved Changes Dialog. 

Thanks for reading, and I would really appreciate your feedback. Please feel free to leave a comment in this blog post.