Cortex Continuous Integration Best Practices · continuous automation integration efficiently in large projects. The document describes the Cortex proposed approach with regards to

Cortex Continuous Integration Best

Practices

Cortex Continuous Integration Best Practices

Cortex Ltd © 2016 All Rights Reserved Page 2

Contents

Preface .................................................................................................................................... 4 Audience ............................................................................................................................. 4 Related Material ................................................................................................................ 4 Revisions to this Document .............................................................................................. 4

1 Overview ....................................................................................................................... 5

2 Platform Diagram ........................................................................................................ 6

3 Environment Details .................................................................................................... 7 3.1 Development ........................................................................................................... 7

3.1.1 Purpose .......................................................................................................................... 7

3.1.2 Before starting to use this platform ........................................................................ 7 3.2 Test ........................................................................................................................... 8

3.2.1 Purpose .......................................................................................................................... 8

3.2.2 Before starting to use this platform ........................................................................ 9 3.3 UAT ........................................................................................................................... 9

3.3.1 Purpose .......................................................................................................................... 9

3.3.2 Before starting to use this platform ...................................................................... 10 3.4 Pre-Production ...................................................................................................... 10

3.4.1 Purpose ........................................................................................................................ 10

3.4.2 Before starting to use this platform ...................................................................... 11 3.5 Production ............................................................................................................. 11

3.5.1 Purpose ........................................................................................................................ 11

3.5.2 Before starting to use this platform ...................................................................... 11

4 Automation of Continuous Integration .................................................................. 12 4.1 Automation of Deployment ................................................................................ 12

4.1.1 Overview ..................................................................................................................... 12

4.1.2 Cortex Flows Promotion Process ............................................................................. 12 4.2 Test Automation ................................................................................................... 14

4.2.1 Overview ..................................................................................................................... 14

4.2.2 Test Automation Process Example ......................................................................... 15 4.3 Cortex API Calls .................................................................................................... 17

4.3.1 Generate Authentication Token ............................................................................. 17

4.3.2 Export .......................................................................................................................... 17

4.3.3 Upload ......................................................................................................................... 18

4.3.4 Import .......................................................................................................................... 18

4.3.5 Publish ......................................................................................................................... 19

4.3.6 Deploy.......................................................................................................................... 19



4.3.7 Debug ........................................................................................................................... 20

4.3.8 Start Flow ................................................................................................................... 20


Preface

Audience

This document provides an overview of Continuous Integration with Cortex

Related Material

None.

Revisions to this Document

The following revisions have been made to this document

Revision Notes

0.1 First Draft

0.2 Review

1.0 First release


1 Overview

This document describes the recommended architecture and processes to implement continuous automation integration efficiently in large projects. The document describes the Cortex proposed approach with regards to environments and how to achieve functionality promotion between these.


2 Platform Diagram

For an enterprise deployment, the diagram below details the typical stages to be followed to progress new flows into production. There may be up to 5 Cortex instance types to map to the different stages:

1. Development 2. Test 3. UAT 4. Pre-Production 5. Production

Each instance type has specific considerations which will be detailed in the following sections.

ProductionProduction

Production

Pre-Prod tests completedFeature(s) Tested

Bug(s)tested

Feature(s) completed

Bug(s)fixed

Development Test

Approvers

Flow segregation is achieved with Cortex Studio AD groups authorisation

Pre-Production

Bug Raised

&Assigned to Development team

Test Team Lead 1

Test team 1

Pre-Prod lead

Test team 1

Pre- Prod Lead

Test team 1

UAT Team Lead

UAT Team

Development Technical Lead 1

Development team 1

Development Technical Lead 2

Development team 2

Instance TypeLegend:

DB

APP

DB

APP

Primary Secondary

AutomatedTestAutomated

TestAutomatedTest

Geo-Resilient Platforms

Continuous development and release

UAT

UAT Team Lead 1

Test team 1

UAT Team Lead 1

Test team 1

UAT Team Lead

UAT Team

UATSign off

Pre-Prod lead

Pre-Prod

Test Instances of 3rd Party Systems Live Instances of 3rd Party Systems


Cortex Ltd © All Rights Reserved Page 7

3 Environment Details

3.1 Development

3.1.1 Purpose

The development instance is used for all development activities. New functionality is created, existing functionality is modified, and unit and functional tests are performed in this instance.

This instance has the same Cortex and Cortex component versions as the production instance and is identically configured. When a solution is required to interact with third-party systems, this instance requires connectivity and authorisation to those systems development instances to enable an efficient development process.

The Cortex platform allows multiple teams to develop in the same instance, as the Cortex Studio Authorisation provides authorisation/access control at a flow/subtask level granularity.

Users granted access to Cortex Studio must be assigned either ‘View’ or ‘Edit’ authorisation rights to either view-only or edit a flow or group of flows respectively.

Although a single development instance might suffice, there are some events that would cause the development to be segregated and to stand another development platform:

1. If connectivity to a required system is not in place from the current development environment.

2. If a new development team does not have access to the current development environment.

3. In the unlikely event of too many groups and flow authors simultaneously needing to work on the development environment (A single Cortex instance should support 20+ active users at a time).

Once the functionality is developed and unit and functional tested, it is ready to be moved to the Test instance where more comprehensive testing will be performed. At this stage the team requires signoff and approval from the Development Technical Leader.

3.1.2 Before starting to use this platform

• A High-Level Design document must be produced by the designer(s). This document includes:

o Architecture of the system including all impacted systems, components and applications

o Functional design for all the system components

o Performance metrics and testing requirements detailed, if applicable

• Access and authentication to the impacted systems must be in place

• Flow authors must have access to this platform, with the correct role based permissions



3.2 Test

3.2.1 Purpose

The Test instance is used for the testing teams to execute the test cases. It supports test execution with hardware, software and network configuration as identical as possible to the production instance. The test setup is configured as per the need of the functionality under test. When a solution is required to interact with other systems, this instance requires connectivity and authorisation to those systems testing instances.

There are several types of testing performed at this stage:

• Functional testing: ensures individual functionality meets the requirements

• Integration testing: individual functionality is combined and tested as a group and meets the solution requirements

• Stress testing: evaluates how the solution behaves under unfavourable conditions. Testing is conducted at edge or beyond the limits of the requirements

• Performance testing: evaluates the speed and efficiency of the solution and ensures the performance requirements are meet

• Usability testing: tests the user interface from the end-user perspective and evaluates if it is user-friendly and easy to use/learn

• Regression testing: ensures existing functionality is still working as per the requirements after modifications are done to related functionality

Tests can be either executed manually without the support of tools or scripts, or automatically.

1. Manual test

• Allows human observation, which is critical when testing for ease of use

• Requires human resources

• Preferable for one-off tests

2. Automatic test

• Allows tests to be run multiple times over a long period of time

• Faster test execution

• Requires time to build the automated tests

When multiple test teams need to run tests against different solutions in the same platform, the below should be considered:

• Stress and performance testing need to be coordinated between the teams so that the platform is as close as possible to a normal operating state

• Platform configuration changes need to be coordinated between the teams to ensure it does not affect current testing



As with the development platform, although a single test instance might suffice, there are some events that would cause the tests to be segregated and to stand another test instance:

1. If coordination between test teams is not possible, failing to complete the planned tests.

2. When the test experience degrades, and the system becomes slow due to platform overload.

3. If connectivity to a required system is not in place from the current test instance.

4. If the designated test team does not have access to the current test instance.

Once all the scheduled tests are run and successfully passed, the solution is ready to be deployed into UAT. At this stage the team requires signoff and approval from the Test Leader.


• Test cases for all types of tests, as defined in section 3.2.1, if applicable, targeting the requirements of the functionality to be delivered must be written

• Test execution plan must be defined, e.g. sequence of testing, priority of test cases and number of test cases to be targeted

• Test data preparation and execution plan must be completed

• Complete development iteration. This can either be:

o Minimum viable solution package

o New features into an existing solution package

o Bug fix(es) release into an existing solution package

3.3 UAT

3.3.1 Purpose

The UAT instance is used for the last phase of testing. During UAT, the end users of the solution, test it to make sure it can handle required tasks in real-world scenarios, according to the requirements. It supports test execution with hardware, software and network configuration as identical as possible to the production instance and contains partial live data.

As with the development platform, although a single UAT test instance might suffice, there are some events that would cause the tests to be segregated and to stand another test instance:

1. If coordination between UAT teams is not possible, failing to complete the planned tests.

2. When the test experience degrades, and the system becomes slow due to platform overload.

3. If connectivity to a required system is not in place from the current UAT instance.

4. If the designated UAT team does not have access to the current UAT instance.



Once all the scheduled tests are run and successfully passed, the solution is ready to be deployed into Pre-Production. At this stage the team requires signoff and approval from the UAT Leader.


• A UAT approach and specification document must be produced by the UAT team. This document includes:

o UAT test use cases for all types of tests, as defined in section 3.2.1, if applicable, targeting the requirements of the use cases to be delivered

o Details on the test execution plan, e.g. sequence of testing, priority of test cases and number of test cases to be targeted

o Test data preparation and execution plan

o UAT entry criteria should be defined

E.g: System test completed, UAT test cases agreed, UAT test environment ready and UAT resources available

o UAT exit criteria must be defined, including the maximum allowed defect count for the UAT to be signed off

E.g: All UAT test cases executed, UAT maximum defect count specification

• Complete test iteration. This can either be:

o Minimum viable solution package tested

o New features into an existing solution package tested

o Bug fix(es) release into an existing solution package tested

• User training and user guide finalised

3.4 Pre-Production

3.4.1 Purpose

The Pre-Production environment is used to test the deployment of the solution and ensure that the deployment can be rolled-back. The deployment guide should be followed carefully to ensure that there are no missing steps. This environment can also be used to:

• Replicate production issues

• Test any emergency fixes required

• Confirm that the Live third-party systems are accessible and working as in the test environments

The Pre-Production environment has hardware, software and network configuration as identical as possible to the production instance, contains partial or as complete as possible live data. This environment must have connectivity to the Live instances of any third-party systems to allow for all testing and debugging to be completed.




• UAT has been signed off

• Deployment and installation guide finalised

3.5 Production

3.5.1 Purpose

The Production environment is the environment where the solution is put into operation for their intended uses by end users. Depending on the solution requirements regarding continuity and uptime, a high availability or disaster recovery environment configuration might be required.


• Deployment successful on pre-production



4 Automation of Continuous Integration

4.1 Automation of Deployment

4.1.1 Overview

In order to achieve continuous integration, Cortex flows and any associated functionality of the solution need to be promoted between the environments. The below should be taken into consideration:

• Cortex flows

The promotion of Cortex flows can be completed manually by exporting and importing flow packages, however Cortex provides the capability of automating this process. This process is explained in section 4.1.2

• Application configuration

• Other custom applications

E.g.: External user interfaces

• Other custom databases

The promotion of these will depend on the implementation and deployment process. If it is understood and documented, it can be automated together with the Cortex flows promotion process achieving an end-to-end automated promotion process.

4.1.2 Cortex Flows Promotion Process

The manual deployment process of Cortex flows is described below:

High Level Step Description

1. Export flows

This step is used to get a flow package saved and ready to be imported onto the target system.

a. User with administrative rights logins to the source server Cortex Gateway

b. Navigates to the Settings > Studio Export menu

c. Selects the required flows and subtasks to be exported

d. Exports the flows

e. Saves the flow package in a defined location

It is advisable to always save the flows package in the same location. This location should be backed up outside the server securely

It is advisable to apply a naming convention to the saved packages. E.g.: <ProjectName>-<ReleaseDate>

2. Move flows This step is used to move the required flow package from the source server to the target server:



a. User accesses the target server and copies the required flow package to a defined folder

It is advisable to always save the flows package in the same location.

3. Import package

This step is used to import a flow package:

a. User with administrative rights logins to the target server Cortex Gateway

b. Navigates to the Settings > Studio Import menu

a. Selects the required flow package to be imported

b. Imports the flows

4. Publish package

This step is used to publish a flow package:

a. After the flows are imported into the target server, an option to publish is presented

b. Publish the flows

In order to automate the above process, Cortex exposes several API calls to perform the below actions:

• Export flow package (see 4.3.2)

• Import flow package (see 4.3.4)

o To import a flow package, it is required to first upload the flow package (see 4.3.3)

• Publish flow package (see 4.3.5)

The below process diagram represents an automated implementation of the promotion of Cortex flows using Cortex.



Start

End

Export flows

Move flows to target server

directory

Start(Scheduled)

Check for studio package in target

directory

Upload studio package

Import studio package

Publish studio package

End

Export and Move Upload, Import, Publish

Figure 1 – Automated promotion process

The process relies on two flows, one on the source server and one the target server.

1. The source server flow is triggered manually by an authorised user and will export the specified flows using Cortex’s export API and then copy the studio package to the target server.

2. The target server flow is a scheduled flow which will be running to monitor the target directory for changes. If there is a change and a Cortex studio package is detected the package will be uploaded to Gateway using Cortex’s upload API, the package can then be imported using the import API. Once the package is imported it can be published using the publish API.

4.2 Test Automation

4.2.1 Overview

Test automation supports the delivery of test results and shortens test execution cycles. It is the method by which software is used to control test executions and the comparison of the outcomes of the tests. This is invaluable when working with large repositories of flows that are used in multiple projects, as for example, if a subtask is used in three different projects



and requires a change, steps must be carried out to ensure that none of these changes are breaking its use. In a small repository for a single project, testing manually would suffice, however, in a large repository this can become time consuming. It is also difficult to keep track of the many use cases that a subtask may be required for. Therefore, it is important to write unit tests for flows and subtasks that are going to be reused, store them and easily execute them regularly to ensure their normal operation.

The process of test automation life cycle includes:

• Test design and planning

Tests should be designed and planned to ensure the functional requirements of the functionality being tested are met. If the functionality changes overtime, it will be required to modify previous tests or add additional tests to ensure the new requirements are tested.

• Test management and execution

Test management and execution tracks the relationship of tests to requirements, organise the test cases, save the test configuration, execute or plan the execution of the test cases and report on the test execution.

4.2.2 Test Automation Process Example

This section illustrates an implementation of test automation using Cortex.

In this implementation the test design is completed using Cortex:

• Flows to be tested do not require any additional implementation. All that is required is to set defined inputs and expected outputs.

• Subtasks to be tested require a test flow to be created. This flow should expose the subtask inputs and outputs as global variables of the flow, so that the flow can be called and exposed through the Cortex Flow API.

Test management is achieved using a database to store test cases associated with flows, its inputs and expected outputs, and a user graphical interface (Liveportal) to allow users to create, manage and view test executions.

As seen in the figure below, the database is composed of 4 tables:

• Groups: this is used to group flows and test cases. If there are multiple projects or sets of tests to be run regarding a specific function, these should be grouped for easier traceability and management.

• Flows: this table holds the flow to run the test against.

• TestCases: this table holds the test cases to be run against a flow in a specific group.

• Parameters: this table holds the inputs the test case requires to run and the expected outputs. When a test case is run, the flow is triggered with the specified inputs and the outputs are compared with the expected outputs stored in this table.



Groups Flows TestCases Parameters

GroupIDPK

GroupName

FlowIDPK

FlowName

GroupID

TestCaseIDPK

TestCaseName

FlowID

ParameterIDPK

ParameterName

ParameterValue

ParameterType

TestCaseID

Figure 2 – Example database schema

Test execution is achieved by using the same user graphical interface, LivePortal, to execute a test case, or a set of test cases, and report on the test case execution. For this, a Cortex flow needs to be developed to read the test case configuration from the database, start a flow via the Cortex Flow API, compare the flow outputs with the expected outputs and generate a test result report.

The Cortex flow API exposes several calls that are useful for such implementation:

• Deploy a user’s flow (see 4.3.6)

• Debug a user’s flow (see 4.3.7)

• Start a deployed/published flow (see 4.3.8)

At a high level, below is an overview of the test automation process :

Get names of flows to be tested and the

related test cases

Trigger flow with specified input

arguments

For each test case

Read output from flow and check it’s

correct

Start

End

Start

Select flow to add test case to

Add test case with input and output

parameters

End

Save to database



4.3 Cortex API Calls

4.3.1 Generate Authentication Token

This request will generate an access token based on a user’s credentials. This token can be used to authenticate and authorise the user for subsequent requests.

Request:

Request URL: <CortexGatewayURL>/token Method: POST Content-type: application/json Body: grant_type=password&username=<username>&password=<password>

Response:

{ "access_token": "", "token_type": "", "expires_in": "", "refresh_token": "", "userName": "", "userId": "", "roles": "", ".issued": "", ".expires": "" }

4.3.2 Export

Export the master version of a flow

Request:

Request URL: <CortexGatewayURL>/api/Flows/export Method: POST Authentication: Bearer <access_token> Content-type: application/json Body: {"flows":["<flowUUIDs>"]}

Response:

[ { "success": true, "id": "<flowUUID>", "name": "<flowName>" } ]



4.3.3 Upload

Upload a studio package to Cortex, required before it can be imported.

Request:

Request URL: <CortexGatewayURL>/api/Flows/upload Method: POST Authentication: Bearer <access_token> Content-type: application/json Form Data: file: (binary)

Response:

{ "tree": [ { "id": "", "$$treeLevel": "", "name": "", "cortexId": "" }, { "id": "", "name": "", "filePath": "", "parentId": "", "$$treeLevel": "", "type": "", "cortexId": "", "hasUncommittedChanges": "" } ], "packageId": "" }

4.3.4 Import

Import the uploaded package into Cortex

Request:

Request URL: <CortexGatewayURL>/api/Flows/upload Method: POST Authentication: Bearer <access_token> Content-type: application/json Request Payload: "<packageID>"



Response:

No response data

4.3.5 Publish

Import the uploaded package into Cortex. To get the server ID run the following query:

SELECT Id FROM [CortexWeb].[dbo].[Servers] Request:

Request URL: <CortexGatewayURL>/api/Flows/publishPackage Method: PUT Authentication: Bearer <access_token> Content-type: application/json Request Payload: { "Flows": [ "<flowIDs>" ], "Servers": [ "<serverID>" ] }

Response:

No response data

4.3.6 Deploy

This request will deploy the user’s flow to the server

Request:

Request URL: <CortexGatewayURL>/api/Flows/deployPackage Method: PUT Authentication: Bearer <access_token> Content-type: application/json Body: {"flows":["<flowUUID>"],"sandbox":false} Response:




4.3.7 Debug

This request will deploy the user’s flow to the user’s sandbox on the server. The name of the flow container will take the following format, ‘<flowName>-<username>@<domain>’

Request:

Request URL: <CortexGatewayURL>/api/Flows/debug Method: PUT Authentication: Bearer <access_token> Content-type: application/json Body: {"flows":["<flowUUIDs>"],"sandbox":false}

Response:


4.3.8 Start Flow

The Start Flow request uses the flow API and not gateway therefore, the request will require a different URL and authentication. The flow API URL and credentials can usually be found in the following path ‘C:\Program Files (x86)\Cortex\Cortex Flow Interface Service\ Innovise.Cortex.Web.Owin.dll’. The credentials can be encoded into the correct format using Postman or the following: https://www.blitter.se/utils/basic-authentication-header-generator/ .

Request:

Request URL: <FlowAPIURL>/api/flow/startflow Method: POST Authentication: Basic <encodedUsernameAndPassword> Content-type: application/json Body: { "NAME": "<FlowName>", "ARGUMENTS": { <enter variable key value pairs here> }, "RETURNPARAMETERS": ["*" // specify global variables to be returned ] }

https://www.blitter.se/utils/basic-authentication-header-generator/

https://www.blitter.se/utils/basic-authentication-header-generator/

Documents

Cortex Continuous Integration Best Practices · continuous automation integration efficiently in large projects. The document describes the Cortex proposed approach with regards to