Workflow Automation CoE > Flows > Best Practices > Action Designer General
Action Designer Best Practices General
Action Inputs and Output Guidelines
- All input labels should be Upper Camel Cased with spaces.
- Instead of JSON (JavaScript Object Notation), use Complex object representations.
- Do not keep default internal names, change the internal name to match the Display name in all lowercase with no spaces or special characters.
- Use the Reference.Table output and map the full record instead of a String with just the sys_id of a record. This saves you an extra Look Up Record step after using this action.
Action Description Guidelines
ServiceNow standard for Action description includes five primary sections:
- Overview - A sentence or short paragraph describing the action.
- Inputs -- list all the inputs and their usage.
- If any of the input takes in a search query statement, provides a sample query and a hyperlink that points back to the vendor's API doc for query syntax reference
- Outputs -- list all outputs and their format if possible.
- Error Messages -- A list of potential error messages only if the action will return error messages.
- Footer -- Any additional caveats/info and notes.
Dealing with Large sets of data
- When virtualizing data or representing tabular data of a third-party system, use Remote Tables.
- Do not use remote tables if you have more than 1000 records.
- For data retrieval that that exceeds 1000 records, use Data Stream actions.
- If the data is not tabular, use Complex Objects to create a structured object (like JSON).
Naming Convention
- Include a Description for your Action.
- Action name should be "human readable", i.e. not a system/function name. Assume the user consuming the action is not highly technical or aware of the APIs.
a. E.g. "Start Virtual Machine". - Words in action names should be separated by a space, every word should begin with an uppercase character.
a. Correct: "Upload File".
b. Incorrect: "UploadFile" or "Upload file". - Action Inputs and Outputs should be "human readable", i.e. not an internal name with special characters. Assume the user consuming the action is not highly technical or aware of the APIs.
a. E.g. "Incident List" not "incident_list". - Use 'Look up' as the prefix if the purpose of the action is to search for object(s), Use 'Get' as the prefix if the purpose of the action is to get details of an object given its unique ID.
a. Correct: 'Get Issue Details by ID', 'Look up Records by JQL'.
b. Incorrect: 'Lookup Issue By ID', 'Get Records By JQL'. - Don't use versioning in the action name. Versioning is at the application scope level. If you need a new action, deprecate the old one and rename it "My Action (Deprecated)".
- E.g. I have Create Issue in the Jira v1 spoke.
Now, with the NY releases and we want to support introspection and break the contract with the original action. - The originally action should be.
- renamed to Create Issue (Deprecated) and marked inactive -- which means it will still run in any flows it was used in, but no longer be visible in the action picker within Flow Designer.
- When creating generic named actions, use "dynamic natural language" feature to automatically display more meaningful action name. For example:
- In the action composer, click on the "..." at the upper right hand corner-->Change Default Title
- Depending on how the action is composed, pick the right dynamic template or dynamic choice field to make sense out of this action title.
- When the flow or subflow calls this generic action now, it will now update the title dynamically.
Guidelines for creating new actions
- Actions should be created in the spokes that are relevant. Don't duplicate the same action in multiple spokes. E.g. If you have an Azure AD spoke that does user management for all Azure and Office 365 services, when you create a spoke for MS Teams, don't duplicate user management in Teams. Ensure the Azure AD spoke has what you need. A solution may require support of multiple spokes.
- By default, set scope access to "Accessible from all scopes" in actions. The scope should only be reduced if a spoke is proprietary to a given application. E.g. Benchmarks may have a spoke that is only ever used by the Benchmark app.
- Follow Action Naming Conventions outlined above while giving a name to an action.
- Provide Description by following Action Description Guidelines.
- Flow Annotations are generally used by a Flow Designer to provide context when authoring a flow. Annotations on an action are optional. Only use annotations if the flow step needs extra description e.g. do not have annotation that repeats what the action name or subflow e.g. My Action is Create User, an Annotation that says, "This action will create a user" has negative value and creates noise on the flow.
- Actions should have a category unless there are only a few actions in the entire spoke.
- Follow Step Guidelines while creating new steps.
- Test your action to ensure the outcome is expected.
- Simulate unhappy path testing, to ensure expected error handling and recovery occurs based on your use case.
- Optionally, create an ATF (Automated Testing Framework) test to validate the outcome of your action.
- Remember to publish your action after you've tested.
