Scaffolding a new service with custom data based on user input

Developers often need to spin up new services for use cases like feature development and architecture processes. Doing this manually can be error-prone and inconsistent across teams. The Workflow in this example streamlines the service creation process by guiding you through a form to input service information then automatically handling the rest: creating a new repository based on your input, creating an entity in Cortex that includes custom data and a linked repository, and automatically opening a Jira ticket to ensure visibility and tracking.

This ensures that every new service is created in a consistent, auditable, and operationally ready way.

This Workflow contains the following blocks:

• A User input block to collect the service name and service tag, and a toggle to select whether or not the incident process was documented.

• A Scaffolder block to create a new repository

• An "Add custom data for entity" Cortex block that adds a key to the entity called incident-process-documented and uses the "Incident process documented" information that was collected during the User input block as the value of the key.

• An HTTP request block that creates a Jira ticket for the security team to review

Using a Workflow to Scaffold a new service, add custom data, and create a Jira ticket

Prerequisites

Before getting started:

• Create a Jira API token with the write:issue:jira permission.

• Your Cortex role must have the permissions Edit Workflows, Execute Workflow runs, Configure Scaffolder templates, and Execute Scaffolder.

• You should have already configured your version control provider integration with write access.

• Make sure you have already registered your Scaffolder template.

  • In this example, we use the cookiecutter-spring-boot repository.

Step 1: Start creating the Workflow

Follow the steps in the documentation to create a Workflow and configure its basic settings.

Step 2: Add a User input block

This block contains the three fields that a user is prompted to fill out when the Workflow is run.

1. Click + in the center of the page. In the block library modal, select the User input block.

2. In the side panel, enter a name and unique slug for the block.

3. Click +Add user input. Configure the input:

   1. Name: Enter Service Name.

   2. Key: Enter service-name.

   3. Description: Optionally enter a description for this input.

   4. Required: Toggle this setting on if you want to require your users to enter input for this field.

   5. Type: Select Text.

   6. Click Add input.

4. Click +Add user input again. Configure the input:

   1. Name: Enter Service Tag.

   2. Key: Enter service-tag.

   3. Description: Optionally enter a description for this input. In our example, we add a description to ensure that users understand what an entity tag is in Cortex: The entity tag is a unique identifier that's used throughout Cortex. Do not use spaces. Example: my-service

   4. Required: Toggle this setting on if you want to require your users to enter input for this field.

      • If you are asking for a unique entity tag, we recommend setting this field as required.

   5. Type: Select Text.

   6. Click Add input.

5. Click +Add user input again. Configure the input:

   1. Name: Enter Incident Process Documented.

   2. Key: Enter incident-process-documented.

   3. Description: Optionally enter a description for this input. In our example, we add a description to ensure that users understand what this step is asking for: Has the incident process been submitted to your team lead?

   4. Required: Toggle this setting on if you want to require your users to enter input for this field.

   5. Type: Select Toggle.

   6. Default value: In our example, we set this to False to ensure users don't accidentally send a false positive.

   7. Click Add input.

6. Click Save at the bottom of the side panel.

Step 2: Add a Scaffolder block

This block creates a new repository in your connected Git integration, using templating to apply the outputs of the User Input step as the project name, app name, and repository name.

1. Click + in the center of the page. In the block library modal, select the Scaffolder block.

2. In the side panel, enter a name and unique slug for the block.

3. Under Scaffolder template, select your template. In this example, we use the Spring Boot Template.

4. Select the option to Create a new repo.

5. Add override variables. The Variable dropdown pulls in all the variables that are able to be overridden in the Git provider and in the Scaffolder template. In this example, we apply the following overrides:

   • project_name: actions.user-input.outputs.service-name

     • This overrides it with the output of the "Service name" field from the User Input block earlier in the Workflow.

   • creator: context.initiatedBy.email

     • This overrides it with the email address of the person who initiated the Workflow.

   • app_name: actions.user-input.outputs.service-name

     • Like the project_name override, this one also overrides it with the output of the "Service Name" field from the User Input block.

   • publisherRepoName: actions.user-input.outputs.service-tag

     • This overrides it with the output of the "Service Tag" field from the User Input block earlier in the Workflow. This ensures that the repo name matches the entity tag in Cortex.

6. Click Save at the bottom of the side panel.

Step 3: Add Cortex custom data block

Earlier in the Workflow, the User Input step prompts a user to enter a service name, tag, and to use a toggle to indicate whether the incident process was documented.

The Add custom data for entity block determines where the user's response (the custom data) is recorded. Running this step results in the output of the Incident Process Documented toggle being added to an entity.

1. Click + in the center of the page. In the block library modal, select the Add custom data for entity block.

2. In the side panel, enter a name and unique slug for the block.

3. Configure the custom data details:

   1. Entity tag or ID, use templating to reference the service tag provided by the user during the User Input step: {{actions.user-input.outputs.service-tag}}

   2. Key: incident-process-documented

   3. Value: "{{actions.user-input.outputs.incident-process-documented}}"

4. Click Save at the bottom of the side panel.

Step 4: Add an HTTP request block

This step creates a Jira ticket for tracking and security review.

1. Click + in the center of the page. In the block library modal, select the Add custom data for entity block.

2. In the side panel, enter a name and unique slug for the block.

3. Configure the HTTP request:

   1. HTTP method: Select POST.

   2. URL: Enter your Jira API URL.

   3. Headers: Include an authorization header and set the value to your Jira token.

   4. Payload: In the payload, you can choose the project in Jira where you want the ticket created, and you can include other information such as the title of the Jira ticket (the summary) and the description of the ticket (the content:text). See Jira's API documentation for more information on formatting the payload. In this example, we include the following payload:

{
  "fields": {
    "project": {
      "key": "SEC"
    },
    "summary": "Entity ready for security review.",
    "description": {
      "type": "doc",
      "version": 1,
      "content": [
        {
          "type": "paragraph",
          "content": [
            {
              "type": "text",
              "text": "New service ready for review."
            }
          ]
        }
      ]
    },
    "issuetype": {
      "name": "Task"
    }
  }
}

1. Click Save at the bottom of the side panel.

When you are finished adding blocks, click Save Workflow at the top of the page.

Run the Workflow

• At the top of the Workflow, click Run.

  • You will be redirected to a page showing the Workflow's steps.

The following chain of events occur during the run:

1. The User input block runs

The User Input block runs, which pauses the Workflow until you enter responses.

Action required

Enter a response for the service name, service tag, and incident process toggle. When you're done, click Submit.

• In this example, we enter Docs test as the Service Name, docs-test as a Service Tag, and toggle on the option for Incident Process Documented.

  

2. The Scaffolder block runs

The Scaffolder block runs, which prompts you to configure and run the Spring Boot Template that was selected while configuring the Scaffolder step.

• Because of the overrides that were configured in the Scaffolder step, the Project Name, App Name, Creator, and Repository fields are pre-filled:

  

  • The overridden fields cannot be edited unless you select the option to make override fields editable while configuring the Scaffolder block.

Action required

During this step, you must also select the organization to create the repository in, include the branch name and a commit message, and choose the visibility of your repo. When you are finished, click Submit.

• After submitting the configuration, a repository is created in the organization you selected:

  

3. The Add Custom Data block runs

The newly-created entity for the repository now contains the incident-process-documented key and value. You can see this in the Output tab of the block during the Workflow run:

You will also see custom data appear on the entity details page. When we view the newly-created Docs test entity details page, the incident-process-documented data appears in the entity's Custom data & metrics sidebar link:

There is no action required during this step.

4. The HTTP request block runs

A ticket is created in Jira requesting a review from the security team. The title and description were set automatically based on the payload provided while configuring the HTTP request step:

There is no action required during this step.