RapidResponse Embedded

Algorithms Guide
As announced at Kinexions 2024, RapidResponse is being renamed Maestro.
Updates are in progress, so you'll start to see RapidResponse and related
components change to Maestro.

SU EA 2.5.0
Kinaxis Confidential Information – for use by Kinaxis Inc. (together with its affiliates, “Kinaxis” or “we”) and
authorized customers and partners of Kinaxis only.
If you are a licensed user of the software product(s) addressed in this documentation, you may print, or
otherwise make available, a reasonable number of copies of the documentation for internal use in connection
with that software, provided that all Kinaxis copyright notices and legends are affixed to each reproduced copy.
The right to print, or otherwise make available, copies of the documentation is limited to the period during
which the applicable license for such software remains in full force and effect. If the license terminates for any
reason, it is your responsibility to certify in writing to Kinaxis upon request that all copies and partial copies of
the documentation have been returned to Kinaxis or destroyed.
All specifications, claims, features, representations, and/or comparisons provided are correct to the best of our
knowledge as of the date of publication, but are subject to change without notice. While we will always strive to
ensure our documentation is accurate and complete, this document may also contain errors and omissions of
which we are not aware.
THIS INFORMATION IS PROVIDED BY KINAXIS ON AN “AS IS” BASIS, WITHOUT ANY OTHER WARRANTIES OR
CONDITIONS, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABLE
QUALITY, SATISFACTORY QUALITY, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, OR THOSE
ARISING BY LAW, STATUTE, USAGE OF TRADE, COURSE OF DEALING OR OTHERWISE. YOU ASSUME THE
ENTIRE RISK AS TO THE RESULTS OF THE INFORMATION PROVIDED. WE SHALL HAVE NO LIABILITY TO YOU
OR ANY OTHER PERSON OR ENTITY FOR ANY INDIRECT, INCIDENTAL, SPECIAL, OR CONSEQUENTIAL
DAMAGES WHATSOEVER, INCLUDING, BUT NOT LIMITED TO, LOSS OF REVENUE OR PROFIT, LOST OR
DAMAGED DATA OR OTHER COMMERCIAL OR ECONOMIC LOSS, EVEN IF WE HAVE BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES, OR THEY ARE FORESEEABLE. WE ARE ALSO NOT RESPONSIBLE FOR CLAIMS
BY A THIRD PARTY. OUR MAXIMUM AGGREGATE LIABILITY TO YOU AND THAT OF OUR DEALERS AND
SUPPLIERS SHALL NOT EXCEED THE COSTS PAID BY YOU TO PURCHASE THIS DOCUMENT. SOME
STATES/COUNTRIES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR
INCIDENTAL DAMAGES, SO THE ABOVE LIMITATIONS MAY NOT APPLY TO YOU.
Copyright © 2020-2024 Kinaxis Inc. Trademarks, including but not limited to KINAXIS, RAPIDRESPONSE and
MPO are the trademarks or registered trademarks of Kinaxis Inc. and/or affiliates, and the exclusive rights to
such trademarks are expressly reserved. All other trademarks are the property of their respective owners. Except
as set out herein, this document may not be reproduced or transmitted in any form (whether now known or
hereinafter discovered or developed), in whole or in part, without the express prior written consent of Kinaxis.
Kinaxis RapidResponse contains technology that is protected under a global patent portfolio, including those
patents listed here: [Link]
This document may include examples of fictitious companies, products, Web addresses, email addresses, and
people. No association with any real company, product, Web address, email address, or person is intended or
should be inferred.

RapidResponse Embedded Algorithms Guide

Date of Publication: Wednesday, August 14, 2024

Published in Canada.

Support: support@[Link]
Web site: [Link]
Contents

Contents 4
CHAPTER 1: Overview 1
About embedded algorithms 2
New and changed features in RapidResponse 3
2024 embedded algorithm changes 4
2022 embedded algorithm changes 5
Requirements 6
Set up your environments 8
CHAPTER 2: About Kinaxis 11
Customer Support 11
CHAPTER 3: Accessing help and documentation 13
Determining which help system or guide to use 15
CHAPTER 4: Defining the data model schema 19
The RapidResponse data model 21
The Data Model interface 25
Customizing the data model 29
Creating custom namespaces 31
Table-based embedded algorithms 35
Define a table- based embedded algorithm 36
Owning tables 37
Defining global algorithms 40
Global dependencies 41
Managing algorithms 44
Designing custom tables and fields 45
Data model dependencies 47
Creating enumerations 48
Dependency filters 49
Identify if dependency tables should be filtered 50
Apply a dependency filter 52
Custom tables and fields 54
Reference and set fields 56

RapidResponse Embedded Algorithms Guide 4

Contents
 Extension fields 58
Creating custom input tables and fields 59
Creating embedded algorithm tables and fields 63
Copying tables 67
Modifying or deleting custom table and fields 69
Validating and applying data model changes 71
Validating data model changes 72
Viewing pending and unsaved changes 73
Undoing data model changes 74
Applying data model changes 75
CHAPTER 5: Writing code for an embedded algorithm 77
The Embedded Algorithm extension 79
Creating a new embedded algorithms project 84
Stub code 86
Family calculations 87
Editing algorithm code 89
Code library modules 90
calendar-math library module 91
date-helpers library module 96
unit-of-measure library module 100
Updating an embedded algorithm 109
Using multiple algorithms 109
Publishing an embedded algorithm 111
CHAPTER 6: Testing and debugging embedded algorithms 113
Test an algorithm using a worksheet 114
Validate your algorithm 118
Trigger the algorithm 118
Configure warning settings 119
Review error dumps 122
CHAPTER 7: Packaging and deploying an embedded algorithm 123
Migrating embedded algorithms 124

5 RapidResponse Embedded Algorithms Guide

Contents
CHAPTER 1: Overview
About embedded algorithms 2
New and changed features in RapidResponse 3
Requirements 6
Set up your environments 8

This guide provides information about creating and deploying embedded algorithms in
RapidResponse.
Embedded algorithms are logic written in code to solve a business problem, expand a solution, or
simplify workbook complexity. The algorithm runs on a separate machine and communicates
with the RapidResponse data server to display the results of the algorithm calculations.
This code is maintained, updated, and owned by the author(s) of the embedded algorithm.
For more on what the requirements are to create embedded algorithms, see "Requirements" on
page 6.
For more about the RapidResponse data model, tables, fields, and data packages, this guide
references topics in the following RapidResponse Help Guides:
l RapidResponse Data Model and Algorithm Guide
l RapidResponse Data Integration Guide
l RapidResponse Resource Authoring Guide
l RapidResponse Administration Guide

The Guides are available at the Documentation Center.

RapidResponse Embedded Algorithms Guide 1

 About embedded algorithms
Embedded algorithms are code written to perform calculations on input or calculated data from
RapidResponse. The algorithms run on a separate machine and communicate with the On-
Demand RapidResponse service using the embedded algorithms agent service. The results from
the algorithm are sent back to RapidResponse to populate fields in the RapidResponse data
model. Users then see the results in RapidResponse resources where they can view and edit data.

Embedded algorithms can be table-based or global. See "Table-based embedded algorithms"

on page 35 and "Defining global algorithms" on page 40.
There are four parts to creating and deploying an embedded algorithm:

1. Define the data model schema—you must first customize the RapidResponse data to
include the namespace, tables, and fields used in the embedded algorithm. See "Defining
the data model schema" on page 19.
2. Write the algorithm—the code for an embedded algorithm is written in TypeScript. See
"Writing code for an embedded algorithm" on page 77.
3. Test and debug the algorithm—standard debugging practices for TypeScript apply.
When testing the algorithm in an instance of RapidResponse, error logs are available for
download and assessment. See "Testing and debugging embedded algorithms" on page
113.
4. Package and deploy the algorithm—the algorithm and data model changes are
packaged in an integration package (.ipk) for export to RapidResponse. See "Packaging
and deploying an embedded algorithm" on page 123.

Note: For more about the algorithms agent, see the RapidResponse Administration
Guide.

2 RapidResponse Embedded Algorithms Guide

CHAPTER 1: Overview
New and changed features in
RapidResponse
This section describes new embedded algorithm features. There are similar chapters in other
documentation guides.
l "2024 embedded algorithm changes" on page 4
l "2022 embedded algorithm changes" on page 5

Note: Descriptions of changes that occurred more than two years ago are removed at
the beginning of each year.

You can also earn more about the new features and changes included in RapidResponse from
the RapidResponse Release Summary Guide.
A new version of the RapidResponse Release Summary Guide is released with each new version of
RapidResponse, including service updates.
This document is available for download from the Kinaxis Knowledge Network and summarizes
the changes to RapidResponse. It contains a compilation of changes gathered from every
RapidResponse guide and help system. It also contains lists of defects resolved in each version.

To access the RapidResponse Release Summary Guide

1. On the Help menu, click Kinaxis Knowledge Network.
2. Sign into the Kinaxis Knowledge Network.
You can create a new Kinaxis Knowledge Network account if you do not have one. An
account is required.
3. On the Knowledge menu, click Documentation.
4. Under Release Summary Documents, select a release to download the PDF document.

Tip: You can also find release summary information in the Global Help system.

RapidResponse Embedded Algorithms Guide 3

New and changed features in RapidResponse
 2024 embedded algorithm changes
The following 2024 releases include changes to embedded algorithms:
l EA 2.5.0

EA 2.5.0
Updated tools
An updated version of [Link] and Visual Studio Code are required to create, edit, and debug
embedded algorithms version EA 2.5.0. The required minimum versions are:
l [Link]: 20.9 or later
l Visual Studio Code: 1.6.1

Compatibility of older projects and code

Embedded algorithm code and projects created with tool versions earlier than EA 2.5.0 don't
need to be upgraded and previously published algorithms will run on the 2.5.0 version of the
Embedded Algorithms Agent.
However, when compiling older code or projects, you may encounter errors that are the result of
a TypeScript compiler upgrade.

Set extension fields on owning tables

Previously, extension fields could only be specified on calculated fields on tables other then the
owing tables. Now you can also specify extension fields on a calculated field on the owing table.
See "Extension fields" on page 58.

Set fields for calculated reference fields in global algorithms

When you add a calculated reference field to a global algorithm, you can choose to generate a
corresponding set field that includes all of the records that point to the referenced record.
See "Reference and set fields" on page 56.

Family calculations
You can now group records into families and perform a single calculation on the whole family.
Families of records can be used to improve algorithm performance or to exercise supply chain
logic on the algorithm calculations.
See "Family calculations" on page 87.

4 RapidResponse Embedded Algorithms Guide

CHAPTER 1: Overview
2022 embedded algorithm changes
The following 2022 releases include changes to embedded algorithms:
l Service Update H2209
l EA 2.4.0

Service Update H2209

Embedded algorithms extensions and updates
Depending on which version of RapidResponse you are using, extension auto-update should be
actively enabled or disabled. For details, see "The Embedded Algorithm extension" on page 79.

EA 2.4.0
Filter data from dependent tables
You can filter the data from owner or global dependency tables to limit the data used by an
embedded algorithm. For some algorithms, excluding unnecessary or irrelevant data can
improve performance.
See "Dependency filters" on page 49.

Track record counts and data request sizes

To help ensure that embedded algorithms do not surpass defined input size limits, you can
configure warnings based on the number of records in one or all of the tables used by a
calculation. In addition, you can monitor the total data size of the algorithm.
See "Configure warning settings" on page 119.

View algorithm properties

You can view properties for embedded algorithms created in read-only namespaces.
See "Managing algorithms" on page 44.

Valid date ranges

The last valid date for date ranges in RapidResponse has been extended to December 31, 2099.

RapidResponse Embedded Algorithms Guide 5

New and changed features in RapidResponse
 Requirements
Embedded algorithms are only available in the On-Demand RapidResponse service. For more
about RapidResponse installations, see the RapidResponse Administration Guide available at the
Documentation Center.
To create embedded algorithms in RapidResponse, you require the following skills and tools:

Skills
l Fluency in typescript—all embedded algorithms are written in TypeScript. See "Writing
code for an embedded algorithm" on page 77.
l Understanding of the RapidResponse data model—the structure of the input and
output data for the algorithm must first be defined in the RapidResponse data model. See
"Defining the data model schema" on page 19.
l Workbook authoring*—understanding how to create worksheets to display the results of
an algorithm is an asset. See the RapidResponse Resource Authoring Guide available at the
Documentation Center.
* Recommended skill

Tools
Installed by IT department
l [Link]—this is used to run embedded algorithm code. See About [Link] (external link).
The required version is 20.9 or the latest 20.x [Link] release. For the latest release version,
click here (external link). Download the 64-bit version of the file that ends in "-[Link]".
l Visual Studio Code—this is where the code for the embedded algorithms is written,
debugged, and published from.
The required environment is Visual Studio Code version 1.61 or higher. See "Set up your
environments" on page 8.

Note: If you are running a RapidResponse version earlier than H2209, you must
disable auto-updates in Visual Studio Code. This ensures that you don't run an
Embedded Algorithms extension that might be incompatible with your version of
RapidResponse. See "The Embedded Algorithm extension" on page 79.

6 RapidResponse Embedded Algorithms Guide

CHAPTER 1: Overview
Installed by developer
l Embedded Algorithms extension—this extension for Visual Studio Code provides the
necessary communication and scripting tools to create embedded algorithms. This
extension is available in the Extensions Marketplace. See "The Embedded Algorithm
extension" on page 79.
l Code Library Modules—these modules provide the ability to work with date, calendar,
and unit of measure data in RapidResponse. See "Code library modules" on page 90.

Provided by Kinaxis
Contact Kinaxis Customer Support for access to the following tools:
l Development instance of RapidResponse— where you define the data model schema for
an embedded algorithm and test the algorithm. Kinaxis will configure this for you. See
"Defining the data model schema" on page 19 and "Set up your environments" on page 8.
l Feature enabled—the embedded algorithms feature must be enabled on all instances of
RapidResponse that will run embedded algorithms. Kinaxis will configure this for you. See
"Set up your environments" on page 8.

RapidResponse Embedded Algorithms Guide 7

Requirements
 Set up your environments
To create embedded algorithms you need:
l Coding environment
l RapidResponse development environment
l Embedded algorithms enabled on all your RapidResponse environments

Your coding environment

The supported coding environment to write and debug your code for embedded algorithms is
Visual Studio Code. Visual Studio Code is an open-source code editor available for Windows,
Linux, and macOS platforms.
To set up your coding your coding environment, you must:
l Install Visual Studio Code version 1.61 or higher. This is the required version to develop
embedded algorithms.
l Disable automatic updates. See opting out of VS Code auto-updates (external link).

Caution: Later versions of Visual Studio Code are not supported by Kinaxis and might be
incompatible.

Note: Visual Studio Code is installed by your IT department.

8 RapidResponse Embedded Algorithms Guide

CHAPTER 1: Overview
Your RapidResponse development environment
The RapidResponse development environment is an instance of RapidResponse used to define
the data model schema for the algorithm and test the functionality of the algorithm.
Part of creating embedded algorithms is defining the structure of the data used in the algorithm
calculations, including where the results are output. These customizations to the RapidResponse
data model are made and verified on a test system to ensure that the production instance of
RapidResponse used by your company isn’t negatively impacted or disrupted during algorithm
development.
After testing and verifying that data model customizations and the embedded algorithms work
as expected, the data model changes and algorithm code are ported to your production instance
in an integration package. See "Packaging and deploying an embedded algorithm" on page 123.

Note: The data in your test system should be a data package imported from the
production instance of RapidResponse to ensure that your test environment accurately
reflects the current state of the production environment. See Set up the
RapidResponse test environment in the RapidResponse Administration Guide.

Enabling embedded algorithms functionality

All instances of RapidResponse that run embedded algorithms—development, QA, and
production instances—must all have the embedded algorithms feature enabled. Contact Kinaxis
Customer Support.

RapidResponse Embedded Algorithms Guide 9

Set up your environments
CHAPTER 2: About Kinaxis
Customer Support 11

Kinaxis enables our customers to improve and accelerate analysis and decision-making across
their supply chain operations.
We help leaders across multiple industries, including A&D, Automotive, High Tech, Industrial, and
Life Sciences to create a foundation for concurrent planning, continuous performance
monitoring, and coordinated responses to plan variances across multiple areas of the business.
Our single-product offering supports a full spectrum of supply chain related business processes,
including S&OP, supply planning, capacity planning, demand planning, inventory management,
MPS, and order fulfillment.
Our customers have immensely complex supply chain networks and volatile business
environments. Yet, they have been able to replace disparate planning and performance
management tools and realize significant operations performance breakthroughs in planning
cycles, supply chain response times, and decision accuracy. They can easily model varying supply
chain conditions to make both long-term and real-time demand and supply balancing decisions
quickly, collaboratively, and in line with the shared business objectives of multiple stakeholders.
For more information, visit [Link] or the Kinaxis Knowledge Network at
[Link] Kinaxis trades on the Toronto Stock Exchange (TSX:KXS).

Customer Support
The Kinaxis Customer Support team understands demand and supply chain planning, monitoring,
and response, and is experienced in applying RapidResponse to real-world business scenarios.
Areas of expertise include:

RapidResponse Embedded Algorithms Guide 11

 l RapidResponse functionality
l Data extraction and mapping issues
l Technical software compatibility
l Coordination of integration
l Product implementation

If you are a key support contact, you can submit support cases. To submit a support case, log
into the Kinaxis Knowledge Network. You can also contact Kinaxis Customer Support by phoning
1-866-463-7877 or by sending a message to support@[Link].

Kinaxis Knowledge Network

The Kinaxis Knowledge Network is the place to find knowledge about RapidResponse. In one
site, you can:
l Search all knowledge about RapidResponse, including product documentation, knowledge
base articles, and threaded discussions about common questions.
l Review your company's Customer Support requests (and, if you are a key support contact,
create new Support requests).
l Engage with a community of RapidResponse experts in the Discussion Groups.

Go to [Link] and log in today. You can also access the Kinaxis
Knowledge Network from RapidResponse by clicking Kinaxis Knowledge Network on the Help
menu.

12 RapidResponse Embedded Algorithms Guide

CHAPTER 2: About Kinaxis
CHAPTER 3: Accessing help and
documentation
Determining which help system or guide to use 15

The RapidResponse documentation set includes several different help systems and guides, each
dealing with a different area of knowledge. Help for individual resources, such as workbooks is
also available.
In addition to the RapidResponse documentation, you can access a variety of other resources to
help you learn about the capabilities and features in RapidResponse. These include an online
community where you can view how-to videos and find advice, a mailing list that you can use to
keep up to date on supply chain news and upcoming events, and instructor-led training courses.

Accessing RapidResponse help systems and guides

You can access RapidResponse help systems and guides two ways:
l Access documentation directly from the Help menu in RapidResponse.
l For links to all of the available help systems and guides, see "Determining which help system
or guide to use" on page 15.

Account permissions and the Java client Help menu

The list of options that you see when you click the Help menu in the Java client depends on the
permissions that are associated with your RapidResponse account.

RapidResponse Embedded Algorithms Guide 13

 The more permissions you have in RapidResponse, the more options you see on the Help menu.
For example, resource authors have more permission than general users. Links to documentation
that you are less likely to need, based on your permissions, are not shown on the Help menu. For
example, users without administrator permissions do not see Administration Help.
The following table outlines all potential Java client Help menu items and the type of users who
can access them.

Help menu item(s) Available to...

RapidResponse User Help All users
RapidResponse Applications Help
Fundamental Concepts Guide

Resource Authoring Help Authors

Analytics and Data Model Guide
Data Model Posters

Scripting Help All administrators

Users with Script authoring permission

Administration Help All administrators

Data Integration Help Data and system administrators

RapidResponse Web Service Help

Note: Additionally all Help listed above (as well Help supporting the Web and Mobile
clients) can be accessed by any user via the Documentation Center page on Knowledge
Network (available in both HTML and PDF format for each Service Update).

Documentation formats
Most RapidResponse documentation resources are available as both HTML help systems and
PDF documents. Some documentation is only available in PDF format.
HTML help systems are optimized for viewing in a web browser. While it is possible to print
individual topics from HTML help, you will get better results if you print the topic or topics from
the equivalent PDF guide.
PDF guides are optimized for printing. They can be viewed and printed using an application such
as Adobe Reader®. You can download Adobe Reader from the Adobe site at [Link].

14 RapidResponse Embedded Algorithms Guide

CHAPTER 3: Accessing help and documentation
Accessing help for RapidResponse resources
Help is often available in the RapidResponse application window for individual resources of the
following types:
l Dashboards and components
l Worksheets and workbooks
l Scorecards
l Forms
l Scripts
l Responsibility definitions

Determining which help system or guide

to use
The RapidResponse documentation set includes several help systems and guides, each dealing
with a different area of knowledge. The following table summarizes the available documentation,
some of which you can access from the Help menu in RapidResponse.

Title Description
RapidResponse User Guide (Java client) This guide provides Java client users with basic reference and
procedural information. It covers topics such as viewing data,
modifying data as part of simulation, solving business problems,
and customizing the user interface.

RapidResponse User Guide (Web client) This guide provides Web client users with basic reference and
procedural information. It covers topics such as viewing data,
modifying data as part of simulation, solving business problems,
and customizing the user interface.

RapidResponse Applications Guide (Java client) This guide provides information about the RapidResponse
applications that support supply chain planning processes across
different functional areas in the Java client.

RapidResponse Applications Guide (Web client) This guide provides information about the RapidResponse
applications that support supply chain planning processes across
different functional areas in the Web client.

RapidResponse Fundamental Concepts Guide RapidResponse product overview, which includes key
capabilities and the deployment methodology.

RapidResponse Embedded Algorithms Guide 15

Determining which help system or guide to use
 Title Description
RapidResponse Resource Authoring Guide (Java This guide provides information on creating and managing
client) resources, such as workbooks and filters, using the Java client.
Detailed information about RapidResponse Query language is
also included.

RapidResponse Resource Authoring Guide (Web This guide provides information on creating and managing
client) resources, including workbooks, dashboards, and forms using
the Web client. Detailed information about RapidResponse
Query language is also included.

RapidResponse Data Model and Algorithm Description of the RapidResponse data model and associated
Guide (Java client) algorithms. All tables and fields in the data model are listed and
described. This guide also notes changes to the data model
corresponding to the RapidResponse release. Procedures in this
guide are for the Java client.

RapidResponse Data Model and Algorithm Description of the RapidResponse data model and associated
Guide (Web client) algorithms. All tables and fields in the data model are listed and
described. This guide also notes changes to the data model
corresponding to the RapidResponse release. Procedures in this
guide are for the Web client.

Data model posters A series of posters illustrating the structure of tables and fields in
RapidResponse, and the relationships between fields. For more
information, see "Data Model Posters" on page 17.

RapidResponse Administration Guide Information for administrators, covering installation, upgrades,

maintenance, system settings, and user administration.

RapidResponse Scripting Guide (Java client) Information about building custom applications using scripting
language objects, functions, and methods to automate some
RapidResponse processes. Procedures in this guide are for the
Java client.

RapidResponse Scripting Guide (Web client) Information about building custom applications using scripting
language objects, functions, and methods to automate some
RapidResponse processes. Procedures in this guide are for the
Web client.

RapidResponse Embedded Algorithms Guide Information on creating embedded algorithms to perform

calculations on data in RapidResponse.

RapidResponse Web Services Guide Information on using RapidResponse Web services to create
users, resources, and Web service client programs.

16 RapidResponse Embedded Algorithms Guide

CHAPTER 3: Accessing help and documentation
 Title Description
RapidResponse Data Integration Guide Information about integrating enterprise data sources with
RapidResponse, including mapping data from source tables and
fields, customizing the RapidResponse database, extracting data
from enterprise sources, performing data updates to bring new
and updated data into RapidResponse, moving data between
RapidResponse instances, and moving data changes between
RapidResponse and business partners in real-time.

RapidResponse User Guide (Mobile Client) This guide provides information on how to view data in the
Mobile client.

Global Help If you are not sure which help system contains the information
you need, you can search for it in this help system, which
includes information from all of the other help systems.

RapidResponse Release Summary The latest release summary outlines all of the changes that have
been made in RapidResponse EA 2.5.0, including new features
and defect resolutions in service updates. Release summaries
can be found in the Kinaxis Knowledge Network in the
Documentation Center.

Custom Help Your company might have also created custom help specific to
your RapidResponse implementation.

The permissions associated with your RapidResponse account affect the list of guides that you
can access from the Help menu. For more information, see "Account permissions and the Java
client Help menu" on page 13.

Data Model Posters

Users who have permission to create resources such as workbooks and dashboards have access
to the following posters on their RapidResponse Help menus:
l RapidResponse Data Model for Import poster: displays the relationship between the tables
and fields used in the RapidResponse data import process.
l RapidResponse Calculated Data Model poster: displays the relationship between the main
RapidResponse database calculated tables and fields. Calculated fields in the
RapidResponse data model input tables are also displayed.
l RapidResponse Sales & Operations Planning poster : displays the relationship between the
tables used to support the Sales & Operations Planning application.
l RapidResponse Inventory Planning and Optimization poster : displays the relationship
between the tables used to support Inventory Planning and Optimization application.

RapidResponse Embedded Algorithms Guide 17

Determining which help system or guide to use
 l RapidResponse Integrated Project Management poster : displays the relationship between
the tables used to support Integrated Project Management application.
l RapidResponse Historical Supply poster and RapidResponse Historical Demand poster:
displays the relationship between all tables (input, control, and calculated) that are used to
store historical supply data and historical demand data, respectively.

18 RapidResponse Embedded Algorithms Guide

CHAPTER 3: Accessing help and documentation
CHAPTER 4: Defining the data model
schema
The RapidResponse data model 21
The Data Model interface 25
Customizing the data model 29
Dependency filters 49
Custom tables and fields 54
Extension fields 58
Validating and applying data model changes 71

The first step to creating an embedded algorithm is to define the structure of the input and
output data in the RapidResponse data model. This includes the custom namespaces, fields,
tables, and data relationships that the algorithm uses.
The following are defined in the RapidResponse data model:
l A custom namespace that is enabled to support embedded algorithms. The algorithm and
its custom fields and tables will be defined in this namespace. See "Creating custom
namespaces" on page 31.
l An embedded algorithm defined in that custom namespace. This can be a table-based or
global algorithm. The algorithm is used to generate a code stub that contains the data
framework for the algorithm. See "Table-based embedded algorithms" on page 35 or
"Defining global algorithms" on page 40.
l Mapping to the input data the algorithm uses. You can use data from input, calculated,
reference, or set fields in an embedded algorithm. You can also use the results from some
embedded algorithm calculations. See "Owning tables" on page 37 and "Global
dependencies" on page 41.

RapidResponse Embedded Algorithms Guide 19

 l Adding optional filters to dependency tables (owner or global) used by the algorithm. See
"Dependency filters" on page 49.
l Creation of an output location for the data produced by the embedded algorithm. The data
is output to an embedded algorithm field on an input table or on an embedded algorithm
table. See "Custom tables and fields" on page 54.

To learn more about the RapidResponse data model and its interface, see "The RapidResponse
data model" on page 21 and "The Data Model interface" on page 25.

Note: Only RapidResponse data or system administrators can made modifications to the
data model. Data administrators are responsible for loading data into the
RapidResponse database in addition to configuring how calculations take place in
RapidResponse and customizing the data model. System administrator are responsible
for global RapidResponse system settings and configurations and have the same access
and permissions as a data administrator.
For more about the types of administrators, see RapidResponse administration roles
in the RapidResponse Administration Guide.

20 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
The RapidResponse data model
The RapidResponse data model outlines the relationships and data flow between different data
elements in the RapidResponse database. The RapidResponse data model also documents how
data is stored and retrieved from the RapidResponse database.
The diagram below outlines how the different data elements are grouped in the RapidResponse
database.

Namespaces
All embedded algorithms and their custom fields and tables must be defined in a custom
namespace. A namespace is a container object that groups and gives context to tables and fields
in the data model. To add embedded algorithms and embedded algorithm fields and tables to a
namespace, the namespace must be enabled to support embedded algorithms. See "Creating
custom namespaces" on page 31.

RapidResponse Embedded Algorithms Guide 21

The RapidResponse data model
 Tables
RapidResponse stores data in different table types. Embedded algorithms can access the
following table types:
l Input tables
Input tables store data imported from your enterprise data sources. This data is editable in
RapidResponse and can be used as input to an embedded algorithm. For example, the
ScheduledReceipt table contains supply data for parts assigned a due date. See "Creating
custom input tables and fields" on page 59.
Some input tables contain vector data that consists of an array of values. See "Tables
containing vector series data" on page 59.
l Calculated tables
Calculated tables store the data produced by core algorithms in RapidResponse. Core
algorithms are unique to RapidResponse and contain calculations and formulas applied to
your input data. For example, the PlannedOrder table stores recommended supply orders
generated by RapidResponse core algorithm calculations. Data in calculated tables can't be
edited, however you can add embedded algorithm fields to calculated tables to hold the
output from an algorithm.
l Embedded Algorithm tables
Embedded algorithm tables are custom tables that store the data produced by embedded
algorithm calculations. This data cannot be edited. See "Creating embedded algorithm
tables and fields" on page 63.

For more on the other types of tables available in RapidResponse, see Table Types in the
RapidResponse Data Model and Algorithm Guide.

22 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Fields
l Input fields—hold data imported from your enterprise data source. Input fields can only be
added to input tables. See "Creating custom input tables and fields" on page 59.
l Embedded algorithm fields—hold data calculated by an embedded algorithm. Embedded
algorithm fields can be added to input, calculated, or embedded algorithm tables. See
"Creating embedded algorithm tables and fields" on page 63.
l Calculated fields—hold data calculated by an expression you define. Calculated fields can
be added to custom input tables or to embedded algorithm tables. See Creating custom
fields in the RapidResponse Integration Guide.

You can reference any of the above field types by linking it to a field on another table. This links
the two tables in a one-to-one relationship. See "Reference and set fields" on page 56.

For more about function fields or attribute fields see Creating custom fields and Managing
attributes in the RapidResponse Integration Guide.

RapidResponse Embedded Algorithms Guide 23

The RapidResponse data model
 Data types for fields
Each field in a RapidResponse table supports a specific data type. The data type determines the
type of data that the field can hold and the types of queries that can be performed on it.
The table below outlines the data types, required syntax, and default values you can use in
embedded algorithms. For more on each data type see Custom field data types and defaults
in the RapidResponse Integration Guide

Data type Syntax and description Default

value
Boolean Either a Y (Yes or True) or N (No or False) value.

Date yyyyMMdd Undefined

The valid date range is from January 2, 1970 to December 31, 2037.
Undefined, Future, and Past values are also allowed and represent dates outside the
valid range.
All calculations should use the UTC timezone. Users see results in their own
timezone.

DateTime yyyyMMdd HH:mm:SS Undefined

A date and time value with the same range as the Date type, entered in the format
shown above. If you add a time zone value, it should use the UTC timezone. Users
see results in their own timezone.
Undefined, Future, and Past are valid values.

Integer <integer> 0
Whole number. Optionally it can be preceded by a minus sign.
The valid range is -2,147,483,648 to 2,147,483,647.

Money <12345.123456> 0.0

A real number (whole and decimal fraction numbers) with an associated currency.
The valid range is -1.79769313486231E308 to 1.79769313486231E308
Money values can be converted to other currencies or represented as a raw value
with no associated currency. See Specifying a table's currency in the RapidResponse
Integration Guide.

Quantity <12345.123456> 0.0

A real number (whole and decimal fraction numbers). Optionally it can be preceded
by a minus sign.
The valid range is -2,147,483,648 to 2,147,483,647.

Reference A reference to another custom or standard RapidResponse table. See "Reference

and set fields" on page 56.

24 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
 Data type Syntax and description Default
value
String <string>
A series of alphanumeric characters. The string data type should be reserved for key
fields and descriptive information. For other types of information, define a custom
table and create a reference to a field in the table.

Time HH:mm:SS 12:00:00

A time value in the format shown above. You can use the 24-hour format to specify
an explicit time or use hh:mm:ss.
Undefined is not a valid time value for embedded algorithms.
All calculations should use the UTC timezone. Users see results in their own
timezone.

The Data Model interface

All data model customizations are made in the Data Model dialog box where you create custom
tables and fields, add embedded algorithm definitions and enumerations, and define and
manage namespaces to hold those custom tables, fields, and algorithms.

RapidResponse Embedded Algorithms Guide 25

The Data Model interface
 Note: You must be a system or data administrator to access and edit in the Data Model
dialog box.

Each table and field has an icon associated with it that identifies the type of table or field it is.
The icons for each type are identified below.

Icon Table Type Icon Table Type

Standard input Custom input

Standard input with vector data Custom input with vector data

Standard control Embedded algorithm

Standard calculated

26 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
 Icon Field Type Icon Field Type
Standard input Custom input

Standard key Custom key

Standard reference Custom reference

Standard reference key Custom reference key

Standard set Embedded algorithm

Standard vector set Custom set

Standard calculated Custom vector set

Standard calculated reference Custom calculated

Standard hidden key Custom calculated reference

Standard calculated set Function

Function reference

Custom hidden key

Attribute

For more about the different table and field types not covered in this guide, see Table types and
Field types in the RapidResponse Data Model and Algorithm Guide.

View properties in the Data Model dialog box

1. From the View menu, click Data Model.
2. From the Show list, select one of the following:
l All tables—displays all standard and custom RapidResponse input and calculated
tables, and all standard RapidResponse control tables.
l Calculated tables—displays all standard and custom calculated tables.
l Control tables—displays all standard RapidResponse control tables.
l Frequently used tables—displays all tables that have been designated as frequently
used.
l Input tables—displays all standard and custom input tables.
l Tables with fields in namespace—displays only tables that contain fields that belong
to the namespace currently selected in the Namespace list.

RapidResponse Embedded Algorithms Guide 27

The Data Model interface
 3. Optionally, from the Namespace list select the namespace whose tables you want to view.
The list of tables shown is filtered to match the selection in the Show list that belong to
the selected namespace.
4. To display the set fields on each table, select the Show set fields checkbox.

View reference information for a table or field

You can view more information for a selected table or field. For standard RapidResponse tables
and fields, the information link opens the RapidResponse Analytic and Data Model Guide. For
custom tables and fields, the information link opens the properties for that table or field.
l Do one of the following:
l To view help for a table, select it in the Table box and then click the Table information
link.
l To view help for a field, select it in the Fields box and then click the Field information
link.

Tip: You can also reference information for a table or field by right-clicking it and then
clicking Table Information or Field Information.

28 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Customizing the data model
Use the following steps to customize the data model for an embedded algorithm:

1. Set up a test instance of RapidResponse—It is strongly recommended that you make

and verify all data model customizations on a test RapidResponse system. This provides a
safe environment for changes without the risk of negatively impacting a production
instance of RapidResponse or its users. See "Set up your environments" on page 8.
2. Design your custom tables and fields—Before creating custom tables and fields for the
algorithm, you should spend time designing them to ensure that the data structure meets
your business and technical requirements and that the table relationships are valid. See
"Designing custom tables and fields" on page 45.
3. Define a custom namespace—an embedded algorithm and any custom tables or fields
you need for the algorithm must be defined in a custom namespace in your instance of
RapidResponse. See "Creating custom namespaces" on page 31.
4. Define the algorithm in the data model—You must first define the table-based or
global algorithm in the data model before you can map tables and fields to it. See "Table-
based embedded algorithms" on page 35 or "Defining global algorithms" on page 40.
5. Optionally, add any enumerations—Enumerations are defined in the data model for use
in the algorithm. See "Creating enumerations" on page 48.
6. Create your custom tables—Add custom tables to the RapidResponse data model. See
"Custom tables and fields" on page 54.
7. Create your custom fields—Add custom fields to the RapidResponse data model. These
fields can be added to your custom tables or to the standard input and calculated tables in
the RapidResponse data model. See "Custom tables and fields" on page 54.
8. Validate and save the data model changes—As you add custom tables and fields,
validate your changes to ensure that no errors have been created in the RapidResponse
data model. See "Testing and debugging embedded algorithms" on page 113.
9. Add and test data mappings—If you have created custom input fields for your
algorithm, you need to map the fields to columns with the required data. See "Mapping
input data" on page 59.
10. Finalize your data model customizations—After you have finished your changes to the
data model and mappings, you need to apply those changes. This triggers a restart of the
server.

After finalizing the algorithm, the data model changes and published algorithm code are
exported together in an integration package (.ipk). See "Packaging and deploying an embedded
algorithm" on page 123.
At any point you can change the properties for an algorithm or delete it. See "Managing
algorithms" on page 44.

RapidResponse Embedded Algorithms Guide 29

Customizing the data model
 Note: All embedded algorithm tables and fields are custom tables and fields.

30 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Creating custom namespaces
Embedded algorithms and custom tables can only be defined in custom namespaces. A custom
namespace ensures that your custom tables and fields are unique and protects against possible
data naming collisions. The custom namespace must be enabled to support embedded
algorithms and you can identify which namespaces allow embedded algorithms in the
Namespaces dialog box.

Notes:
l You can define multiple embedded algorithms in the same namespace, but
algorithms with the same name must be defined in different namespaces.
l You can only view properties for embedded algorithms created in read-only
namespaces. See "View or modify algorithm properties" on page 44.

Namespace dependencies
Namespaces can have other custom or standard namespaces added as dependencies. The
dependencies define the possible relationships that can be created between tables and fields in
those different namespaces. For example, if you add the Mfg namespace as a dependency then
you can reference fields in tables in that namespaces such as the Part and
IndependentDemand tables. See "Reference and set fields" on page 56.
Namespace dependencies are required by the namespace being created and by default, each
new namespace added to the RapidResponse database is automatically assigned the Core
namespace as a dependency. This is a permanent dependency that cannot be removed. All other
dependencies can be added or removed as required, however removing a dependency can
invalidate data model relationships.
For more on what namespace dependencies affect, see Namespace dependencies in the
RapidResponse Integration Guide.

RapidResponse Embedded Algorithms Guide 31

Customizing the data model
 Note: You can use an owning table in another namespace for a table-based algorithm,
however that namespace must be added as a namespace dependency to the namespace
for the algorithm. See "Owning tables" on page 37.

Create a custom namespace

1. From the View menu, click Data Model .
2. In the Data Model dialog box click Namespaces.
3. Click New.
4. In the New Namespace dialog box, for Name type a unique string to identify the
namespace. This cannot be changed after the namespace is saved for the first time.
The name cannot be more than 16 characters long.
Typically a namespace might be named after the particular business or functional area its
tables and fields are expected to support.
5. Optionally, type a short description of the namespace for Description.
6. For Origin, type the origin (creator) of the namespace. Typically, you might specify your
company name.
7. Select the Allow embedded algorithms checkbox. This enables the namespace to
support embedded algorithms and embedded algorithm tables and fields.
8. Optionally, in the Details box type a longer description and other details about the
namespace such as its intended purpose or usage.
9. In the Dependencies area, to add a new namespace dependency, do the following:
l Click Add.
l In the Add Namespaces dialog box, select a namespace and click Add.
l To view properties for a selected namespace, click Properties.
l After adding all the required dependencies, click OK.
10. Click OK to save the newly defined namespace.
11. Click Close.

32 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
 Copy a custom namespace
When you copy a custom namespace enabled to support embedded algorithms, the copied
namespace is also set to enabled embedded algorithms. All of the embedded algorithms and
embedded algorithm tables and fields in the namespace are also copied. You can modify the
namespace by adding and removing dependencies, but you cannot disable its support for
embedded algorithms.

1. From the View menu, click Data Model .

2. In the Data Model dialog box click Namespaces.
3. Select the namespace and click Copy.
4. In the Name box, type a new name. The name cannot be more than 16 characters long.
5. Optionally, type a short description of the namespace for Description.
6. For Origin, type the origin (creator) of the namespace. Typically, you might specify your
company name.
7. The Allow embedded algorithms checkbox is selected and disabled from editing.
8. Optionally, in the Details box type a longer description and other details about the
namespace such as its intended purpose or usage.
9. Optionally, add or remove any dependencies.
10. Click OK to save the copied namespace.
11. Click Close.

Note: Custom namespaces that support embedded algorithms cannot be copied and
changed to a namespace that doesn't support embedded algorithms.

Delete a custom namespace

If you no longer need a custom namespace, you can delete it from the data model. For example
if a custom namespace has been defined to represent a subsidiary that your company no longer
needs to track data for, you can delete it. Before deleting the namespace you should check the
tables and fields in that namespace and determine if there they have relationships to other
namespaces. If so, remove those dependent namespaces to avoid errors when you delete the
namespace.

Caution: When you remove a custom namespace, all of the embedded algorithms and
custom tables and fields in that namespace are also deleted.

1. In the Data Model dialog box click the Namespaces button.

2. In the Namespaces dialog box, select the namespace you want to delete.
3. Click Delete.

RapidResponse Embedded Algorithms Guide 33

Customizing the data model
 Caution: Deleting a namespace removes all custom tables and fields defined within it.

Remove a namespace dependency

1. In the Data Model dialog box click the Namespaces button.
2. In the Namespaces dialog box, select the namespace you want to remove a namespace
dependency from.
3. Click Properties.
4. In the Dependencies area, select the dependency to remove.
5. Click Remove.

Caution: Removing a namespace dependency can affect the properties of any

embedded algorithms that use it.

Note: You can modify most of the properties for a custom namespace and add or
remove namespace dependencies for it. See Managing namespaces in the RapidResponse
Integration Guide.

Tip: You can also open the Data Model dialog box by clicking the Administration pane
and then clicking Data Model

34 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Table-based embedded algorithms
To create a table-based embedded algorithm, it must first be defined in the data model in a
custom namespace. The algorithm is then included in code stub generated for the custom
namespace. See "Stub code" on page 86. The input data for the algorithm is defined by its
owning and global dependencies.
A table-based embedded algorithm requires the following:
l A name: Specify the name for the algorithm. This is the name assigned to the code stub
generated for the algorithm.
l A unique custom namespace: The algorithm must be defined in a custom namespace in
the RapidResponse data model. This should be the same custom namespace assigned to
the custom tables and fields used by the algorithm. See "Creating custom namespaces" on
page 31.
l An owning table: the algorithm must have an owning table defined. This input table
contains the core data that the algorithm uses for its calculations. The tables in this list
belong to the same custom namespace the algorithm is defined in along with tables in the
Core namespace and any namespace dependencies you have added to the custom
namespace. See "Owning tables" on page 37 and "Namespace dependencies" on page 31.
l At least one dependency relative to its owning table: The owner dependency is defined
as a path that starts from the owning table to a field that is used as input that the algorithm
uses in its calculations. See "Owner dependencies" on page 38.
l Dependency filter: Optionally you can filter the data from owner or global dependency
tables. See "Dependency filters" on page 49.

You can also create global algorithms that don't require an owning table. These types of
embedded algorithms are used to retrieve all of the data for a data point. See "Defining global
algorithms" on page 40.

RapidResponse Embedded Algorithms Guide 35

Customizing the data model
 Define a table- based embedded algorithm
1. From the View menu, click Data Model.
2. In the Data Model dialog box click Embedded Algorithms.
3. In the Algorithms dialog box, click New and then select Table-based Algorithm.
4. In the New Algorithm dialog box, specify the following properties:
l Name—Type a unique string that identifies the algorithm. This will be the name of the
embedded algorithm you will write/edit code for.
l Namespace—Select the custom namespace the embedded algorithm is defined in.
See "Creating custom namespaces" on page 31.
l Runtime provider: Select if the algorithm will be run by RapidResponse or Other it
runs outside of RapidResponse.
l Owner—From the Owner list, select the owning table for the algorithm. See "Owning
tables" on page 37.
5. In the Owner Dependencies area, click Add.
6. In the Select Algorithm Owner Field Path dialog box, select the field you want to use as
input in the embedded algorithm.
7. Click OK.
8. Repeat steps 5 - 7 for each field. Input, calculated, reference, and set fields can be used as
input fields for an embedded algorithm.
9. Optionally, add a global dependency. See "Add a global dependency" on page 42.
10. Optionally, add a filter to any of the owner or dependency tables that you have added. See
"Dependency filters" on page 49.
11. Click OK.

Note: Only input tables can be used as owning tables for table-based embedded
algorithms.

Tips:
l Select a group of adjacent values by holding SHIFT and then clicking the first and last
values in the range.
l Select a set of non-contiguous values by holding CTRL and then clicking the values
you want to select.

36 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Owning tables
Table-based embedded algorithms require an owning table where the core data for the solution
used in the algorithm calculations is located. This table can be any input table in RapidResponse
that has key fields, including custom tables and tables in namespace dependencies on the
algorithm namespace.
As part of defining the algorithm, you must specify the field(s) on the owning table where the
algorithm gets its input data from. These fields can be input, calculated, reference, or set fields.
See "Owner dependencies" on page 38.

Note: Tables without key fields cannot be used as the owning table for an embedded
algorithm. For example, the BillOfMaterial table has no key fields and therefore doesn't
show up in the Owner list of tables.

The owning table is also an origin for the table dependencies for the algorithm. For example, if
you are creating an embedded algorithm to determine shipping costs for orders, you might
select the IndependentDemand table as the owning table. The IndependentDemand table
provides the demands not directly related to demand for other parts and it has dependencies to
other tables that can be used in the algorithm. The diagram below shows how the owning table
and its dependencies have data you might use in your algorithm calculations.

Note: When you create a table-based embedded algorithm table, it requires a reference
field to its owning table for data model changes to be saved in RapidResponse. See
"Creating embedded algorithm tables and fields" on page 63.

RapidResponse Embedded Algorithms Guide 37

Customizing the data model
 Owner dependencies
The dependencies you define on the owning table represent paths to the input data that the
algorithm requires. These paths link embedded algorithm fields on input or calculations tables to
the algorithm's owning table. For example, the embedded algorithm defined below has a path
defined to the DueDate field on its owning table, ScheduledReceipt.

You can also include paths that use reference or set fields from the owning table, however these
paths must end in a field that is a value type (such as string, quantity, or date) on the referenced
table. The Type for the field path cannot be Reference or Set. For example, that paths on the
referenced Part and PartSource fields are [Link], [Link], and [Link].

38 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Using field paths on referenced fields enables you to access data in tables that are referenced
from the owning table. See "Reference and set fields" on page 56.

Notes:
l Field paths that reference other fields can only be 15 levels or fewer from the owning
table. For example, for an algorithm defined on the Site table, a field path of
[Link] is 6 levels from the owning
table, Site.
l You can add a filter to the owner dependency table to exclude unnecessary or
irrelevant data. See "Dependency filters" on page 49.

RapidResponse Embedded Algorithms Guide 39

Customizing the data model
 Defining global algorithms
Global algorithms are a type of embedded algorithm that are used to grab all of the data for a
data point. Unlike table-based algorithms that execute once per record in their owning table,
global algorithms execute just once.
For example, if you wanted to determine the cost of transferring parts between sites, you could
use a global algorithm that is site-based to get all of the site information at once. This would
avoid calculating data for each individual site again and again.
Global algorithms do not have an owning table and must have at least one global dependency
defined.

Caution: Global algorithms typically results in large calculations that can impact
performance. It is recommended that global algorithms are used only when necessary.

Define a global algorithm in the data model

1. From the View menu, click Data Model.
2. In the Data Model dialog box click Embedded Algorithms.
3. In the Algorithms dialog box, click New and select Global Algorithm.
4. In the New Global Algorithm dialog box, specify the following properties:
l Name—Type a unique string that identifies the algorithm. This is the same name as
the embedded algorithm you will write code for.
l Namespace—Select the custom namespace that the embedded algorithm is defined
in. See "Creating custom namespaces" on page 31.
5. In the Global Dependencies area, click Add.
6. Click in the added row do the following:
l Under Table, use the drop-down list to select the table to link to. Only tables from
namespace dependencies display in this list. See "Namespace dependencies" on page
31.
l ln the Field column, click the new row and in the Select Algorithm Global Field
dialog box select the field you want to access data from.
7. Repeat steps 5 - 7 for each field. Input, calculated, reference, and set fields can be used as
input fields for a global algorithm.
8. Click OK.

40 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Global dependencies
Global dependencies enable algorithms to access data from tables in namespace dependencies.
Global algorithms require at least one global dependency. For table-based algorithms, this
includes tables that are not referenced from the algorithm's owning table.

Caution: You can add any number of global dependencies for an embedded algorithm,
however, this can lead to performance issues because all global dependencies in a
namespace are sent for all algorithm requests in that namespace. Table-based
algorithms should only use a global dependency when the algorithm requires all of the
records from a table and is unable to access that data using a referenced field. To
minimize performance issues, it's recommended that smaller tables be used in global
dependencies.

Only tables that are in the same namespace as the embedded algorithm or in a namespace
dependency can be added as a global dependency.
For example, as shown in the image below, if you have a table-based algorithm with its owning
table as ScheduledReceipt, and you want to include data for all part types in the calculation, you
can include a global dependency to the PartType table. This is because the owning table,
ScheduledReceipt, doesn't have a reference to PartType. The PartType tabe belongs in the Mfg
namespace, which is a namespace dependency for the namespace that your algorithm is defined
in, so you can add a global dependency to a field on PartType.

RapidResponse Embedded Algorithms Guide 41

Customizing the data model
 Notes:
l Tables in the Core namespace cannot be added as global dependencies.
l Using tables with vector data series in global dependencies is not recommended.
l If you define global dependencies for two tables with the same name but that are
located in different namespaces, only the first table listed is accepted as a global
dependency for the embedded algorithm.

Add a global dependency

1. From the View menu, click Data Model.
2. In the Data Model dialog box, click Embedded Algorithms.
3. In the Algorithms dialog box, select the algorithm to add a global dependency to.
4. Click Properties.
5. In the Global Dependencies area click Add.
6. Click in the added row, and do the following:
l Under Table, use the drop-down list to select the table to link to. Only tables from
namespace dependencies display in this list. See "Namespace dependencies" on page
31.

42 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
 l In the Field column, click the new row and in the Select Algorithm Global Field
dialog box select the field you want to access data from.
7. If required, repeat steps 5 - 6 to add additional global dependencies.
8. Click OK.

RapidResponse Embedded Algorithms Guide 43

Customizing the data model
 Managing algorithms
You can view properties for all embedded algorithms in your system, however only algorithms
that you have created can be modified or deleted. For embedded algorithms created in read-
only namespaces, such as algorithms imported as part of a third-party application, you can only
view its properties.

View or modify algorithm properties

1. From the View menu, click Data Model.
2. In the Data Model dialog box click Embedded Algorithms.
3. In the Algorithms dialog box, select the algorithm you want to view properties for and
then click Properties.
4. If the algorithm is in a custom namespace that you can edit, make your changes and then
click OK.

Delete an algorithm
1. From the View menu, click Data Model.
2. In the Data Model dialog box click Embedded Algorithms.
3. In the Algorithms dialog box, select the algorithm you want to remove and then click
Delete.

44 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Designing custom tables and fields
Before you add custom tables and fields to the RapidResponse data model, it is highly
recommended that you design them. This is to ensure that you create valid relationships
between custom tables and RapidResponse to import data successfully.
Before customizing the data model, determine the following:

What are the namespace requirements?

A custom namespace is required to hold the embedded algorithm and the custom tables and
fields that it uses. Multiple embedded algorithms can live in the same namespace, however
algorithms with the same name must be defined in different namespaces. See "Creating custom
namespaces" on page 31.
While standard namespaces in RapidResponse cannot be edited, you can add custom fields to
tables that are defined in standard namespaces and use those fields in an embedded algorithm.

What embedded algorithm are you creating?

The algorithm must be defined in the RapidResponse data model before the code for the
algorithm is written. For table-based algorithms, this includes specifying an owning table for the
algorithm. See "Table-based embedded algorithms" on page 35 and "Defining global
algorithms" on page 40.

What enumerations are you adding?

If you are adding any enumerations to an algorithm, you must first define them in the data
model. See "Creating enumerations" on page 48.

What custom tables are you adding?

Depending on what business problem you are resolving using an embedded algorithm, you
need to determine which custom tables you need to satisfy the data requirements. A single
custom table might be adequate or you might require multiple custom tables. See "Custom
tables and fields" on page 54.

What are the key fields for custom input tables?

Any custom input tables require at least one key field. See "Key fields" on page 61.

What are the relationships between tables?

You need to determine the relationships:

RapidResponse Embedded Algorithms Guide 45

Customizing the data model
 l Between custom tables you create.
l Between custom tables you create and the standard tables in RapidResponse.

Relationships are determined by reference fields in a table. A reference field is a link to another
field in another table. The relationship is one-to-one and only contains values stored in the
reference table or the reference field is set to null. See "Reference and set fields" on page 56.
When you add a reference field to a table, a corresponding set field is automatically created in
the reference table. A set field represents a set of summary records in a reference table. See
Determining the relationship between custom tables in the RapidResponse Integration Guide.

Tip: Name reference keys similarly to the table that they reference.

What custom fields to add?

The last design step to determine what custom fields to add to both custom and standard tables.
Custom fields should be added after key fields and owning reference fields are established for
the tables. See "Custom tables and fields" on page 54.

46 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Data model dependencies
Table-based embedded algorithms require an owning table where the core data for the
algorithm calculations is located. This dependency is required and must be defined when the
algorithm is created in the data model. See "Owning tables" on page 37.
To expand the data that an embedded algorithm can access, you can add namespace
dependencies and global dependencies.

Namespace dependency
Namespaces can have other namespaces added as dependencies to enable relationships
between the tables and fields in the linked namespaces. See "Namespace dependencies" on
page 31.

Global dependency
For global algorithms, you must define at least one global dependency. For table-based
algorithms, you can use a global dependency to give the algorithm access to data outside of its
owning table. See "Global dependencies" on page 41

Invalid dependencies
A table-based embedded algorithm cannot depend on it's owning record. For example, you
create an algorithm that calculates cumulative lead times for parts, as shown in the diagram
below. The algorithm uses Part as its owning table and generates data to the LeadTime and
[Link] fields.

When you run the algorithm for Part A, the algorithm also runs calculations on its components,
Parts B and C. The lead time results for Part A depend on the lead time results for Parts B and C.
This is a valid recursive algorithm. See "Recursive algorithms" on page 110. For more about

RapidResponse Embedded Algorithms Guide 47

Customizing the data model
 recursive data structures in the data model, see Recursive data in the RapidResponse Data Model
and Algorithm Guide.
However, if the results for Part A depended on Part A, then that would be an invalid dependency.
In addition, non-owning vector sets cannot be added as dependencies to tables used in
embedded algorithms. A vector table can only be a dependency through a set field that
corresponds to its owning reference. For more on vector data, see the RapidResponse Data
Model and Algorithm Guide (Java client).

Creating enumerations
Enumerations are fields that contain or return values from a list of predefined strings. For
example, you can define an enumeration “Status” with the values “Green, Red, Yellow”. The
embedded algorithm uses these string values when the enumeration is referenced in the
algorithm code.
Enumerations are defined in the data model and must be defined in the same namespace as the
algorithm that uses them. Updates to an enumeration are easily made in the data model instead
of within the algorithm code. Enumerations can only contain string values that start with a letter
and can only contain alphanumeric characters and underscores.

Create an enumeration
1. From the View menu, click Data Model.
2. Click the Enumerations button.
3. Click New.
4. In the New Enumeration dialog box, type a Name that uniquely identifies the
enumeration.

48 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
 5. Select the Namespace the enumeration is defined in.
6. To add a value for the enumeration, click Add.
7. In the new row, type the value.
8. Repeat steps 6-7 for each value.
9. Click OK.
10. Click Close.

Dependency filters
You can add filters to owner or global dependency tables to refine the data used in an
embedded algorithm. For some algorithms, this can improve algorithm performance by
excluding unnecessary or irrelevant data.
It is important to first determine that the algorithm meets the criteria for filtering. See "Identify if
dependency tables should be filtered" on page 50.
Dependency filters only apply to data that is accessed through sets, vector sets, or through
global dependencies. Data from references are not filtered.
To add a filter to an algorithm dependency, you must specify the dependency table and an
expression-based Boolean field on that table. Each dependency table can only have one filter
applied to it and the filter is applied regardless of which set, vector set, or global dependency is
used to access the filter table. See "Apply a dependency filter" on page 52.

RapidResponse Embedded Algorithms Guide 49

Dependency filters
 Identify if dependency tables should be
filtered
Dependency filtering should only be added if an algorithm performs poorly because of extra
unnecessary data in its dependencies. This is because filtering adds complexity, and in some
situations can slow an algorithm. For example, filtering can slow an algorithm if few records are
filtered out and the filtering expression is complex.
To identify if an algorithm would benefit from dependency filtering, examine the data used as a
dependency. If not all the data is required, you can use a dependency filter to reduce the amount
of data required to perform a calculation. Note that there are multiple factors that affect
algorithm performance, with large dependencies being just one possible factor.
The first step to determine if filtering should be applied is to identify if the algorithm has poor
performance because of its dependencies. Then you need to identify which tables to apply a
filter to and what filter expression to use.

Identify dependencies impacting performance

To identify if an algorithm has dependencies impacting performance, do the following:

1. Trigger the algorithm to run on a group of owning records.

2. Open the Embedded Algorithm Details and Log workbook to the Algorithm Information
worksheet. Click Show Details to display all columns.

Algorithms with dependencies that affect performance exhibit the following indicators:
l The Dependency Time takes large percentage of the overall time (Requests > Time).
If the Dependency Time is a large value, the following values also tend to be larger:
l Requests > Size
l Worker > Request > Parse Time
l Worker > Request > Transform time

Identify the table and filter expression to use

After identifying that an algorithm has performance issues tied to its dependencies you then
need to identify the table(s) to filter and which filtering expression(s) to use. Try any of the
following methods:

Identify which records to filter out: Analyze the algorithm code.

If the code includes IF statements that skip over specific records, then a filtered dependency
could replace the IF statement.

50 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
 Caution: If the records are skipped over in some areas but still used in other areas of the
algorithm, then dependency filters should not be used to replace the IF statements.

Identify which dependency tables to filter: Analyze the algorithm dependencies

in the data model schema
If the algorithm depends on known large tables, specifically sets or global tables, then adding a
filter to these specific dependency tables might improve algorithm performance.

Identify which dependency tables to filter: Inspect the request while debugging
the algorithm
Identify a specific owning record that will display performance issues and run the calculation on
that record while in debug mode. Identify the largest tables returned in that request. These
tables are ones that you might filter to improve algorithm performance.

RapidResponse Embedded Algorithms Guide 51

Dependency filters
 Apply a dependency filter
When you add a filter to an algorithm dependency, you need to specify the following:
l The dependency table to filter. Only valid types display in the drop-down list.
l Owner dependency tables accessed through sets or vector sets.
l Global dependency tables.

See "Data model dependencies" on page 47.

Note: Valid tables that meet one of the criteria above that also display data through a
reference will display in the list. However, tables that are accessed only through
references cannot be filtered and won't display in the list.

l The Boolean expression field on that table that contains the filter expression. This field
executes the selection logic for the filter. Only records that the field returns true for are
included in the algorithm calculations.
For more on expressions, see the RapidResponse Resource Authoring Guide (Java client).

Apply a dependency filter

1. Add a Boolean expression field to the dependency table that you want to filter.
2. In the New Algorithm or Algorithm Properties dialog box, in the Filters area click Add.
3. Click in the cell under Table and use the drop-down list to select the table. Only owner
and global dependency tables display in this list.
4. Click in the cell under Field and in the Select Algorithm Filter Field dialog box, select the
Boolean expression field you created in step 1. All Boolean expression fields on the
selected table display in the list.
5. Repeat steps 1 - 3 for each dependency filter you want to add. A dependency table can
only have one filter applied to it.

52 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
 Note: A filter icon displays next to the dependencies where filtering is applied.

View the properties of the filter expression

You can view the properties for the Boolean expression field including the expression definition.
l In the New Algorithm or Algorithm Properties dialog box, in the Filters area click
Properties.

Remove a dependency filter

1. In the New Algorithm or Algorithm Properties dialog box, select the row for the
dependency filter you want to remove.
2. Click Remove.

RapidResponse Embedded Algorithms Guide 53

Dependency filters
 Custom tables and fields
Embedded algorithms use custom tables and fields for input and output data.
Input—embedded algorithms can accept data from input, calculated, reference, and set fields. If
an embedded algorithm field contains calculated results from an algorithm accessing unique
data, the field can be used as input in another embedded algorithm. See "Recursive algorithms"
on page 110.
Output—embedded algorithms can only output data to embedded algorithm fields. These
fields can be added to input, calculated, or embedded algorithm tables.

Custom tables
You can create two types of custom tables to support embedded algorithms:
l Custom input tables—these tables hold information that exists in your enterprise data
source that is not currently stored in the RapidResponse data model. See "Creating custom
input tables and fields" on page 59.
l Embedded algorithm tables—these tables hold data produced by embedded algorithm
calculations. See "Creating embedded algorithm tables and fields" on page 63.

To create custom tables in RapidResponse, you must have at least one custom namespace
defined in the data model. You can create the custom table in the same namespace as the
algorithm that uses it, or you can create the table in a namespace dependency. If the custom
table is defined in a namespace dependency, it must include a key field that references the
owning table for the algorithm. See "Creating custom namespaces" on page 31 and "Owning
tables" on page 37.

Note: As you add custom tables and fields, you can manually validate the data model.
See "Validating data model changes" on page 72

54 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Custom fields
Custom fields store, display, or calculate data that you require in RapidResponse but that is not
included in the standard RapidResponse data model. You can create the following types of
custom fields:
l Input fields: store input data from your enterprise data source that is not currently
included in the standard RapidResponse data model. Input fields can only be added to
input tables or control tables. See "Create a custom input field" on page 62.
l Vector fields: store a vector set that represents a series of vector data values for each
record in a table. These fields are automatically created when you define a table that
contains vector data series. See "Tables containing vector series data" on page 59.
l Calculated fields: display the results of calculated business logic not already calculated in
the RapidResponse data model. RapidResponse query language is used to define how the
field is calculated. Calculated fields can be added to any type of table. See Creating custom
fields in the RapidResponse Integration Guide.
l Embedded Algorithm fields: store the results of embedded algorithm calculations.
Embedded algorithm fields can only be added to input tables or embedded algorithm
tables. See "Create an embedded algorithm field" on page 63.
l Function fields: similar to calculated fields but include one or more arguments that allow
authors to specify input parameters defining how the field is calculated. Function fields can
be added to any type of table. See Creating custom fields in the RapidResponse Data
Integration Guide.
l Extension fields: embedded algorithm field that associates the results of embedded
algorithm calculations on other input records. See "Extension fields" on page 58.

Each field you add to a table is assigned a RapidResponse data type. The data type determines
the data a field can hold and the amount of memory required for each single record containing
that field. See Table size limits in the RapidResponse Administration Guide.

Note: If you add Quantity or Money fields, you can have a unit of measure applied to
their values to convert the values to other units. See Allowing unit of measure conversions
in the RapidResponse Data Integration Guide.

For more on editing other properties for custom tables and fields, see Modifying custom and
standard table properties and Modifying custom and standard field properties in the
RapidResponse Data Integration Guide

RapidResponse Embedded Algorithms Guide 55

Custom tables and fields
 Reference and set fields
Reference fields allow you to link to other tables and access values from a record in a referenced
table. References use the reference [Link] syntax. The syntax specifies the name of the
reference field (which typically matches the table name) and the field name to use from that
table.

In the diagram below, the DemandOrder table has two reference fields: [Link] and
[Link]. The [Link] reference links to the Customer table provide access to that
customer data from the DemandOrder table.

Note: Field paths that reference other fields can only be 15 levels or fewer from the
owning table. For example, for an algorithm defined on the Site table, a field path of
[Link] is 6 levels from the owning table,
Site.

Multiple records can have the same reference or references can consist of multiple tables
connected by a chain of references. For example, in the diagram above the DemandOrder table
links to the Customer table which in turn is linked to the CustomerGroup and Region tables.

56 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
All links between tables are bi-directional. When a reference field is created in a table, a set field
is automatically created in the referenced table that includes all of the records that point to the
referenced record. Set fields are a link between two tables where there is a one-to-many
relationship and allow you to access multiple related records from different tables.
In the example below, on the Customer table, DemandOrders is a set field as each customer can
have more than one demand order.

Note: Set fields return an array of values.

Calculated references
Embedded algorithms can accept a reference to a calculated field or calculated field set as input.
However, the calculated reference cannot be null and the referenced table must belong to a
namespace that is a dependency for the embedded algorithm’s namespace.

Note: Only calculated tables and fields can reference calculated results.

Recursive references
Embedded algorithms do not accept recursive references. Reference fields on a table that point
back to the same table are recursive references.

Calculated set fields

Embedded algorithm calculated reference fields can only generate corresponding set fields in
the following two cases:

RapidResponse Embedded Algorithms Guide 57

Custom tables and fields
 l The owning reference field on an embedded algorithm table will automatically generate a
corresponding set field. This set field cannot be modified.
l Embedded algorithm reference fields that are calculated by a global algorithm will generate
a corresponding set field that can be used as a dependency or as an owner path for an
extension field. This type of extension field can be used to set up a family calculation. See
"Extension fields" on page 58 and "Family calculations" on page 87.

Extension fields
Extension fields give you the ability to associate the results of an embedded algorithm with other
input records, either with records on the owning table of the algorithm or with records on other
input tables. For example, an extension field would allow you to run an algorithm per site and
output fields on each of the current site’s parts for each calculation.
These fields create an array for each table that has them and initially have an undefined value
because the algorithm will calculate those values. Extension fields on each relevant input field
must have a value assigned to them by the algorithm.
Extension fields are created by creating an embedded algorithm field on an input table or on the
owning table for the algorithm and defining an owner path. See "Create an extension field" on
page 65.

58 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Creating custom input tables and fields
Custom input tables and fields store data contained in your enterprise data source that is not
currently included in the RapidResponse data model. Input fields can only be added to custom
or standard RapidResponse tables.

Mapping input data

When you add a custom input field to an input table, you must specify where to get the data to
populate the field. This requires mapping the field to the column in the data file from your
enterprise system. This ensures that the input data is current every time data is imported or
updated in the system. For details on how to map custom input fields, see Defining field maps in
the RapidResponse Integration Guide.

Tables containing vector series data

You can configure custom input tables to hold vector data, which consists of an array of values.
Each vector can hold any number of values that each have the same data type. For example,
instead of having a reference that links to thousands of related records, you can use a vector to
store all those records as a single record. For more, see Vector data in the RapidResponse Data
Model and Algorithm Guide and Creating tables to contain vector series data in the RapidResponse
Integration Guide.

RapidResponse Embedded Algorithms Guide 59

Extension fields
 Create a custom input table
1. From the View menu, click Data Model.
2. In the Data Model dialog box, click Table and then click New Input Table.
3. In the New Table dialog box, specify the following:
l Name—type a name for the table.
The table name must be unique in the namespace it is being added to.
It can only consist of alphanumeric characters (a-z, 0-9) and underscores (_).
l Namespace—select the namespace to add the table to.
New tables can only be added to custom namespaces.
The namespace a table belongs to cannot be changed after the table is saved for the first
time.
l Description—type a description for the table.
4. Optionally, specify the following settings:
l Allow data update to—specify how data in the table is affected by data updates:
l Insert, modify, and delete records—Records are inserted in the table if they
don't exist, modified if they do exist, or deleted if they exist in the table but not in
the data update.
l Insert and modify records only—Records are inserted in the table if they don't
exist or modified if they do exist. Records are not deleted from the table.
l Allow automatic record creation—Values not already found in the table can be
automatically loaded from records on other tables that reference it. Typically, this
occurs during data imports and data updates. See Automatic record creation in the
RapidResponse Integration Guide.
l Frequently used table—The table displays when Frequently used tables is selected
in the Show list in the Data Model dialog box.
l Show list of values in worksheets—If the table contains at least one key string field,
this option is enabled. Worksheet columns that point to this table from a referencing
table display all available values in a selectable drop-down list.

60 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Input fields
When you add a custom input field to an input table, you define that field to hold a particular
piece of data by specifying a specific RapidResponse data type for the field and a default value.
See "Data types for fields" on page 24.
You can also make the input field a reference field that points to data in another table. To create
a reference field, you must select "Reference" as the data type when you create the field. See
"Data types for fields" on page 24 and "Reference and set fields" on page 56.

Key fields
Input tables must have an input field that is a key field. The key field ensures that each record in
the table is unique and it can consist of one or more fields. For example, the ScheduledReceipt
table uses the key fields Line and Order to identify each scheduled receipt record.
Key fields can use any of the following data types:

l String l DateTime
l Reference l Boolean
l Date l Integer
l Time l Enum

Caution: If you have applied changes to the data model and then change keys on a table
afterward, data in that table might be deleted. See "Validating and applying data model
changes" on page 71.

RapidResponse Embedded Algorithms Guide 61

Extension fields
 Create a custom input field
1. From the View menu, click Data Model.
2. In the Data Model dialog box, under Table select the table you want to add the custom
input field to.
3. Click Field, and then click Input Field.
4. In the Field name box, type a descriptive name for the field.
Field names must begin with a letter and can only consist of alphanumeric characters (a-z,
0-9) and underscores (_).
5. From the Field namespace list, select the namespace to define the field in.
New fields can only be added to custom namespaces.
The namespace a field belongs to cannot be changed after the field is saved for the first
time.
6. From the Type list, select the type of data that this field displays.
To make the field a reference field, select Reference in the Type list.
7. If the field is a reference field, select the table that it references in the Referenced table
list and specify the field it references in the Corresponding field box.
8. In the Default value box, type a default value for the field. This is the value that is used in
records when a value is not provided. If you do not specify a default, then a default value is
automatically assigned based on the data type of the field. See "Data types for fields" on
page 24.
9. Optionally, in the Description box type a description of the field.
10. Click one of the following:
l Save and close—save the field and close the dialog box.
l Save—save the field and create another custom input field.
l Close—close the dialog box without saving the field.

62 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Creating embedded algorithm tables and
fields
Embedded algorithm tables hold the data generated by embedded algorithms. In addition, they
can also hold calculated data that an embedded algorithm uses in calculated, function, or
attribute fields.

Create an embedded algorithm table

1. From the View menu, click Data Model.
2. In the Data Model dialog box, click Table and then click Embedded Algorithm Table.
3. In the New Table dialog box, specify the following:
l Name—type a name for the table.
The table name must be unique in the namespace it is being added to.
It can only consist of alphanumeric characters (a-z, 0-9) and underscores (_).
l Namespace—select the namespace to add the table to.
New tables can only be added to custom namespaces.
The namespace a table belongs to cannot be changed after the table is saved for the first
time.
l Algorithm—select the embedded algorithm that can access this table.
The embedded algorithm must be defined in the same namespace as this table.
l Description—type a description for the table.
4. Click OK.
5. You are prompted to define the owning reference field for the table. Do one of the
following:
l Click Yes to create the field now. See "Create the owning reference field for a table-
based embedded algorithm table" on page 65
l Click No to save the table and create the owning reference field later.
You will need to create this field before saving your data model changes when you exit
the Data Model dialog box.

Create an embedded algorithm field

Embedded algorithm fields hold the data calculated by an embedded algorithm. You can add
embedded algorithm fields to embedded algorithm tables, custom input tables, or
RapidResponse input tables.
An embedded algorithm field must be defined in the same custom namespace as the embedded
algorithm that outputs data into the field. See "Creating custom namespaces" on page 31.

RapidResponse Embedded Algorithms Guide 63

Extension fields
 When you add an embedded algorithm field to table that is not the owning table for the
algorithm that will use the field, it is referred to as an extension field.

64 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
 Create the owning reference field for a table-based embedded algorithm table
1. From the View menu, click Data Model.
2. In the Data Model dialog box, under Table select the table you want to add the
embedded algorithm field to.
3. Click Field, and then click Embedded Algorithm Field.
4. In the Field name box, type a descriptive name for the field.
Field names must begin with a letter and can only consist of alphanumeric characters (a-z,
0-9) and underscores (_).
5. From the Field namespace list, select the namespace to define the field in.
New fields can only be added to custom namespaces.
The namespace a field belongs to cannot be changed after the field is saved for the first
time.
6. From the Type list, select the type of data this field displays.
To make the field a reference field, select Reference in the Type list.
7. If the field is a reference field, select the table that it references in the Referenced table
list.
8. Optionally, in the Corresponding field box change the name of the corresponding set
field generated for this reference field.
9. Optionally, in the Description box type a description of the field.
10. Click one of the following:
l Save and close—save the field and close the dialog box.
l Save—save the field and create another embedded algorithm field.
l Close—close the dialog box without saving the field.

Note: Global algorithms don't require an owning table or an owning reference field. See
"Defining global algorithms" on page 40.

Create an extension field

Extension fields can be created on an input table or on the owning table of the embedded
algorithm.

1. From the View menu, click Data Model.

2. In the Data Model dialog box, under Table select the table you want to add the
embedded algorithm field to.
3. Click Field, and then click Embedded Algorithm Field.
4. In the Field name box, type a descriptive name for the field.

RapidResponse Embedded Algorithms Guide 65

Extension fields
 Field names must begin with a letter and can only consist of alphanumeric characters (a-z,
0-9) and underscores (_).
5. From the Field namespace list, select the namespace to define the field in. This should be
the custom namespace you created that is enabled for embedded algorithm.
New fields can only be added to custom namespaces.
The namespace a field belongs to cannot be changed after the field is saved for the first
time.
6. From the Algorithm list, select the embedded algorithm for this field.
7. For Owner Path, click and select the path on the owning table that will be used to find
the owning record for the field's calculation.
8. From the Type list, select the type of data this field displays.
To make the field a reference field, select Reference in the Type list.
9. If the field is a reference field, select the table that it references in the Referenced table
list.
10. Optionally, in the Description box type a description of the field.

66 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Copying tables
You can create copies of existing tables in different namespaces. When you copy a table, in
addition to adding or removing fields, you can specify table properties such as the table’s
currency, if it is frequently used, and if it allows automatic record creation.
The table below outlines how certain fields and table properties behave when a custom or
RapidResponse table is copied.

Field and Description

Table
Properties
Behavior

Input and function You can modify the fields that are used to uniquely identify records in the
fields are copied copied table. See Identifying records in tables in the RapidResponse
Integration Guide.

Currency used to store You can use that default currency or define a different currency using an
Money values is copied expression. See Specifying a table’s currency in the RapidResponse
Integration Guide.

Fields with the Enum If you want to include fields with Enum data, you must create these fields.
data type are not
copied

Field mappings are not You must define the field mappings in the copied table. See Defining
copied field maps in the RapidResponse Integration Guide.

References to tables in Depending on which namespace the referenced table is in, its reference
different namespaces and set fields are copied differently.

RapidResponse Embedded Algorithms Guide 67

Extension fields
 Copy an input table
1. In the Data Model dialog box select the input table to copy.
2. Click Table and then click Copy Table.
3. In the Name box, type the name for the new table.
4. In the Namespace list, select the custom namespace you are copying the table in to.
5. Modify any of the following options:
l Allow data update to
l Allow automatic record creation
l Frequently used table
l Show list of values in worksheets
For more on these options, see "Custom tables and fields" on page 54.
6. In the Description box, type a description of the table.
7. Optionally, on the Currency tab, specify the currency used to store records in this table.
8. Optionally, on the Record Identification tab, specify the fields used to uniquely identify
records in the table.

Tip: You can also copy a table by selecting it, right-clicking and then clicking Copy Table
in the context menu.

Copy an embedded algorithm table

1. In the Data Model dialog box select the embedded algorithm table to copy.
2. Click Table and then click Copy Table.
3. In the Name box, type the name for the new table.
4. In the Namespace list, select the custom namespace you are copying the table in to.
5. In the Description box, type a description of the table.

Note: If you copy a table that contains vector data you are prompted to create the new
table’s owning reference. See Defining vector key fields in the RapidResponse
Integration Guide.

Note: If you copy a table that contains vector data or a convert a copied table to contain
vector data, you cannot specify the table’s currency.

Tip: You can also copy a table by selecting it, right-clicking and then clicking Copy Table
in the context menu.

68 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Modifying or deleting custom table and fields
After creating a new custom table or field, you can modify its properties or delete in from the
data model.

View properties for a table

1. From the View menu, click Data Model.
2. In the Data Model dialog box select the table you want to view properties for.
3. Right-click and then click Properties .

View properties for a field

1. From the View menu, click Data Model.
2. In the Data Model dialog box, select the table that contains the field you want to view
properties for.
3. In the Fields area, select the field.
4. Right-click and then click Properties .

Delete a custom table.

1. From the View menu, click Data Model.
2. In the Data Model dialog box select the custom table to delete.
You might need to change the selections in the Show and Namespace lists if the table
you want to delete doesn’t display.
3. Click Table and then click Delete Table .
The table and all of its fields, including corresponding set fields and reference fields are
deleted.

Note: Any filters based on a deleted custom table are automatically deleted.

Note: Any workbooks containing worksheets based on deleted custom tables cannot be
opened until those worksheets are deleted from the workbook.

Note: Any field maps added for a custom field remain after it is deleted.

Tip: You can also delete a custom table by right-clicking the table name and then
clicking Delete.

RapidResponse Embedded Algorithms Guide 69

Extension fields
 Delete a custom field.
1. From the View menu, click Data Model.
2. In the Data Model dialog box select the table containing the custom field you want to
delete.
3. In the Fields area, select the custom field .
4. Click Field, and then click Delete Field.

Caution: If you delete the owning reference for a vector, all data in the table is deleted
and you must define a new owning reference before you can apply the data model
changes.

Note: Any query expression that uses a deleted field will no longer work.

Note: Any field maps added for a custom input field remain after it is deleted. See To
delete a custom field in the RapidResponse Integration Guide.

Tip: You can also delete a custom field by right-clicking the field in the Fields area and
then clicking Delete.

70 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Validating and applying data model
changes
As you make changes to the data model, you can:
l Save the changes and directly apply the changes to the active data model.
l Save the changes as pending and review all pending and unsaved changes before applying
them to the active data model. See "Viewing pending and unsaved changes" on page 73.

The active data model is the current data model available to all users in the system. Until you
apply your changes to the system, the data model will not display the changes. The best practice
is to save your changes as pending so can view and validate them. This ensures that the changes
are valid and will create no errors in the data model. See "Validating data model changes" on
page 72.
Once you have confirmed that the changes are valid and ready to be applied, you then apply
them to the data model. The RapidResponse server will require a restart after you have applied
the changes. See "Applying data model changes" on page 75.

Notes:
l When published algorithm code that has been updated has been included in an
integration package imported into RapidResponse, the RapidResponse server doesn't
need to be restarted. See the RapidResponse Integration Guide.
l When you add, edit, or remove dependency filters the RapidResponse server does
not have to be restarted. The filter is applied the next time that the embedded
algorithm runs.

RapidResponse Embedded Algorithms Guide 71

Validating and applying data model changes
 Validating data model changes
Before applying any changes to the data model, check that your changes are valid. Any issues
detected are identified by a severity level and message describing the issue with its relevant
table and field names, and its namespace. For example, you might have too many key fields on a
custom table or a field might not be defined in a valid namespace.
Typically you must resolve the issue(s) before you can save or apply the data model changes. If
you receive a warning about the table containing too many fields, redesign the table by
removing the fields or moving them to another table. For more on table size limits, see Table size
limits in the RapidResponse Administration Guide.

Validate your changes to the data model

As you add custom tables and fields, you can manually validate the data model to ensure that
your changes do not result in any errors. Depending on whether or not any of the
customizations are invalid, either a dialog with issue details displays or a message that tells you
that all pending and unsaved changes to the data model are valid.
l In the Data Model dialog box, click Validate Data Model.

Caution: RapidResponse validates any data model customizations you have made and if
they pass validation, commits to them to the pending data model. The pending data
model is also validated and any changes resulting in an invalid data model are not saved
and the error reported. However, it is possible for some issues to not be detected until
after data model changes have been applied. For example, if an expression for a new
calculated field uses a new custom input field that has been added but not yet applied to
the data model, the expression cannot be fully validated until after the other
customizations are applied.

Note: RapidResponse also automatically validates your data model changes when you
click OK and exit the Data Model dialog box.

72 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Viewing pending and unsaved changes
You can view both pending and unsaved changes to the data model in the Data Model Changes
dialog box. Details for the changes, including the nature of the change, and the tables, fields, and
namespaces where the change takes place display here. Changes made by other administrators
also display in the dialog box.
If required, you can undo any unsaved or pending data model change in a selected namespace.
See "Undoing data model changes" on page 74.

View pending and unsaved data model changes

1. In the Data Model dialog box, click View Changes.
2. From the Show list, select one of the following (if applicable):
l All changes—displays all pending and unsaved data model changes on the system,
including changes made by other administrators.
l My unsaved changes—displays only those unsaved changes you have made since
opening the Data Model dialog box.
l Pending changes—displays all changes that are saved as pending, including changes
made by other administrators.
3. From the In namespace list, select the namespace whose data model customizations you
want to view. Select All to view customizations across all namespaces.
4. Optionally, in the Search row, specify the details of the data model change(s) you want to
show by clicking the search arrow to select a column category and then typing in the
Search box.
For example, if you wanted to only show customizations made in the context of the
DemandOrder table, you could select Table from the Search list and then type
“DemandOrder” in the Search box.

Tip: You can also view pending and unsaved changes in the Apply Pending Changes
dialog box by clicking View Changes.

RapidResponse Embedded Algorithms Guide 73

Validating and applying data model changes
 Undoing data model changes
You can undo pending and unsaved changes in the data model by reverting the changes in a
namespace. If you revert a change that results in an invalid data model, you will generate an
error that must be resolved before you can undo the change. For example, if you undo the
pending addition of a new namespace that another namespaces is set to depend on you would
then need to remove the namespace dependency before you can undo the pending addition of
the new namespace.

Caution: Changes made by other administrators are not differentiated from your
changes. Be careful when undoing changes in namespaces that contain pending or
unsaved changes from other administrators.

1. In the Data Model dialog box, click Undo Changes.

2. Select the checkbox next to each namespace whose data model customizations you want
to undo.
For namespaces which other administrators have saved pending changes to, you might
typically want to review the details in the Data Model Changes dialog box to ensure you
understand the impact of undoing these changes.
3. Click Undo Changes.
4. Click OK.

74 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
Applying data model changes
After confirming that all your changes are valid, you then apply the changes to the active data
model. Changes are applied by namespace, including changes in that namespace made by other
administrators. It is a best practice to coordinate data model customizations with other data
administrators working in the same namespaces.
Before applying your changes you can view the properties for a namespace or view pending and
unsaved changes from the Apply Pending Changes dialog box. See "Viewing pending and
unsaved changes" on page 73.

Note: When published algorithm code that has been updated has been included in an
integration package imported into RapidResponse, the RapidResponse server doesn't
need to be restarted. See the RapidResponse Integration Guide.

Tip: You can wait and apply your changes during a defined maintenance window to
restart RapidResponse when applying your data model changes for embedded
algorithms.

Apply data model changes

1. In the Data Model dialog box, click OK.
2. When prompted to apply the changes to the active data model now, click Yes.
3. In the Apply Pending Changes dialog box select the checkbox for each namespace with
pending changes that you want to apply to the active data model.
4. Click Apply and when prompted to restart the RapidResponse server do one of the
following:
l Click Yes to apply your changes and restart RapidResponse.
l Click No to save your changes as pending and apply them to the data model at
another time.

Caution: If you click Cancel, you will lose any unsaved changes to the data model.

Caution: If you want to revert your changes after applying them to the data model, you
will have to manually revert each change and then apply changes to the data model
again.

RapidResponse Embedded Algorithms Guide 75

Validating and applying data model changes
 Caution: RapidResponse validates any data model customizations you have made and if
they pass validation, commits to them to the pending data model. The pending data
model is also validated and any changes resulting in an invalid data model are not saved
and the error reported. However, it is possible for some issues to not be detected until
after data model changes have been applied. For example, if an expression for a new
calculated field uses a new custom input field that has been added but not yet applied to
the data model, the expression cannot be fully validated until after the other
customizations are applied.

76 RapidResponse Embedded Algorithms Guide

CHAPTER 4: Defining the data model schema
CHAPTER 5: Writing code for an
embedded algorithm
The Embedded Algorithm extension 79
Creating a new embedded algorithms project 84
Stub code 86
Family calculations 87
Editing algorithm code 89
Code library modules 90
Updating an embedded algorithm 109
Using multiple algorithms 109
Publishing an embedded algorithm 111

Embedded algorithms are written in TypeScript on an independent machine that communicates

with the RapidResponse server using the Embedded Algorithm extension. See "The Embedded
Algorithm extension" on page 79.
The required development environment is Visual Studio Code version 1.61 or higher. All of the
coding, debugging, and testing on an embedded algorithm takes place in Visual Studio Code.
See "Set up your environments" on page 8.
When you create an embedded algorithm, you are the owner of its code, its custom data model
schema, and any RapidResponse resources created to support the algorithm. You are responsible
for maintaining the code, schema, and resources with updates, including after upgrades.
Each embedded algorithm is a single function that can compute multiple results.

RapidResponse Embedded Algorithms Guide 77

 Input to an embedded algorithm from the RapidResponse server can include:
l Input data from a RapidResponse input table
l Calculated data from a RapidResponse input or calculated table
l Calculated data from an embedded algorithm field or table

Calculated data from an embedded algorithm output to the RapidResponse server can include:
l An embedded algorithm field on a RapidResponse input table
l Records in an embedded algorithm table

Note: You can include multiple output fields or multiple output tables in a single
algorithm.

To create an embedded algorithm, you must do the following:

1. Define the data model scheme in RapidResponse. See "Defining the data model schema"
on page 19.
2. Start a new embedded algorithms project or open an existing project. See "Creating a new
embedded algorithms project" on page 84.
3. Edit the algorithm code stub. See "Editing algorithm code" on page 89.
4. Test and debug the algorithm. See "Testing and debugging embedded algorithms" on
page 113.
5. Publish the algorithm to the RapidResponse server. See "Publishing an embedded
algorithm" on page 111.

Note: When compiling projects that were created with Embedded Algorithm tools that
are versions earlier than EA 2.5.0, you might encounter errors in the code that have to be
fixed. This is because of a TypeScript compiler upgrade.

78 RapidResponse Embedded Algorithms Guide

CHAPTER 5: Writing code for an embedded algorithm
The Embedded Algorithm extension
The Embedded Algorithm extension connects to a specified RapidResponse data server and
enables communication between the server and the embedded algorithms project you are
developing.
Depending on your version of RapidResponse, you can access the extension the following ways:
l For RapidResponse version H2209 or later, you will automatically have the latest extension
through extension auto-updates in Visual Studio Code.
l For RapidResponse versions prior to H2209, extension auto-update must be disabled in
Visual Studio Code. You must download and install extension version 2.14.4 from Visual
Studio Code Marketplace. See "Install the extension" on page 81.
For more about using the Visual Studio Code Marketplace and how to disable auto-
updates, see Extension Marketplace (external website).

Note: If you disabled extension auto-update and are using RapidResponse H2209 or
later, you must enable auto-updates. In Visual Studio Code, set the
[Link] setting to True.

When you open the extension, you can open a folder with an existing embedded algorithm
project (Open Folder) or create a new project (Create Embedded Algorithms Project).

The extension provides access to all of the commands you need to create, debug, validate, and
publish algorithm projects. Depending on whether you are starting a new project or have an
existing project open, different command options display. See "Extension commands" on page
80
When you initially connect to the server, stub code is generated for all of the algorithms defined
in a selected namespace. "Creating a new embedded algorithms project" on page 84

RapidResponse Embedded Algorithms Guide 79

The Embedded Algorithm extension
 Extension commands
A set of standard commands is provided as part of the embedded algorithms extension to create
and then work with an embedded algorithm project in Visual Studio Code.

The table below provides an overview of the available commands.

80 RapidResponse Embedded Algorithms Guide

CHAPTER 5: Writing code for an embedded algorithm
 Command Description

Create Use this command to identify the location of the RapidResponse server, download the
Embedded appropriate data model schema, and generate code stubs for algorithms in the specified
Algorithms namespace.
Project See "Creating a new embedded algorithms project" on page 84.

Change Data Use this command to connect to a different server from the server you initially specified when
Server Location you created the embedded algorithms project.

Validate Use this command to generate a static compile of the embedded algorithm code. See "Testing
Algorithms and debugging embedded algorithms" on page 113.

Update Project Use this command to update your embedded algorithms project with the latest data model
schema from the RapidResponse server. See "Updating an embedded algorithm" on page 109.

Trigger Use this command to debug an algorithm by running the algorithm on a specified record
Algorithm without opening a worksheet in the RapidResponse server. See "Trigger the algorithm" on
page 118.

Download Error Use this command to download and import error dump files for the embedded algorithms
Dump project from the RapidResponse server. See "Review error dumps" on page 122.

Import Error Use this command to import error dump files downloaded for the embedded algorithms
Dumps project from a production instance of RapidResponse. See "Review error dumps" on page 122.

Publish Project Use this command to generate the algorithms in your embedded algorithms project and
upload that code to the RapidResponse server. See "Publishing an embedded algorithm" on
page 111.

Note: If you do not save your credentials, you will be prompted to sign in with your user
name and password each time you run a command.

Install the extension

For RapidResponse versions prior to H2209, you must manually install the Embedded Algorithms
extension.

1. In Visual Studio Code, click Extensions.

2. Type Kinaxis.
The Embedded Algorithms Developer Tools extension displays.

RapidResponse Embedded Algorithms Guide 81

The Embedded Algorithm extension
 After installation, you will need to reload Visual Studio Code.

Running behind a proxy

The Embedded Algorithms extension supports running behind a proxy if you apply the proxy
setting in Visual Studio Code.

1. In Visual Studio Code click File.

2. Select Preferences and then click Settings.
3. Click Application to expand the list and then click Proxy.
4. Type your proxy server information.
5. Close the Settings tab.

Note: For more on extensions in Visual Studio Code, see Extension Marketplace.

Use Single Sign-In with the Embedded Algorithms extension

If your RapidResponse servers are configured with Single Sign-In, to authenticate the extension
you need to generate a developer API token to use in Visual Studio Code.

Generate an API token

1. In RapidResponse, on the Tools menu click Options.
2. Click the Settings tab.
3. Click Manage My Token.
4. In the My Developer API Token dialog box, click Generate New Token.
5. Click Copy to Clipboard to copy the token value.
6. In Visual Studio Code, when prompted for a password when connecting to a

82 RapidResponse Embedded Algorithms Guide

CHAPTER 5: Writing code for an embedded algorithm
 RapidResponse data server, paste the copied API token for the password.
7. When prompted to save your credentials, click yes.

Cautions:
l Your API token is like a password and should not be shared.
l After you generate the token and close the dialog box, the token value will not be
revealed again. If you need a new token, you will have to revoke the old token and
generate a new one.

Note: If you do not save your credentials in Visual Studio Code, you will be prompted for
the API token or your password every time run a command.

Revoke an API token

1. In RapidResponse, on the Tools menu click Options.
2. Click the Settings tab.
3. Click Manage My Token.
4. In the My Developer API Token dialog box, click Expire New Token.

RapidResponse Embedded Algorithms Guide 83

The Embedded Algorithm extension
 Creating a new embedded algorithms
project
To successfully develop, test, and publish algorithms, your development environment must be
connected to a RapidResponse server. Clicking the Create Embedded Algorithms Project button
connects with the RapidResponse data server you specify and downloads the defined data
model schema for a selected namespace.
This schema is used to generate the stub code for all algorithms in that namespace. The stub
code contains all of the inputs and outputs for the algorithm that were defined in the data
model and provides a starting place for you to write your code. See "Stub code" on page 86.

Each embedded algorithm is a single function that can compute multiple results. You can include
multiple output fields or multiple output tables in a single algorithm.

Notes:
l The RapidResponse data server must be running for the extension to successfully
connect to it.
l Input data from RapidResponse is not sorted when the algorithm is run. Instead, if
you require the data to be sorted, include a sort function in the algorithm code.
l At any time to change the RapidResponse server that the project is linked to, you can
run the Change Data Server Location command. See "Extension commands" on
page 80.
l Depending on how the data model has been configured, multiple code stubs can be
generated in a single embedded algorithms project.

84 RapidResponse Embedded Algorithms Guide

CHAPTER 5: Writing code for an embedded algorithm
Create a new embedded algorithms project
1. In Visual Studio Code, click the Embedded Algorithms extension tab .
2. Click the Create Embedded Algorithms Project button.
3. Specify which folder you want to save the project in and click Select project location.
4. Specify the location of the RapidResponse data server.
5. Specify your username and password.
6. Optionally, select yes to save your sign in credentials now, or select no. If you select no
you will be prompted for your credentials each time you run a command.
7. Select a namespace from the list of valid namespaces.
Only namespaces enabled to support embedded algorithms display in the list. See
"Creating custom namespaces" on page 31.
8. Enter a project name and a project description.

You are now connected to the specified RapidResponse server and can start editing the
generated code stubs. See "Editing algorithm code" on page 89.

Notes:
l Each algorithm has its own code stub and must be edited individually.
l After upgrading to Embedded Algorithms 2.5.0, previously saved credentials will be
lost and you will need to retype them when authenticating with RapidResponse. As
before, you can choose to save your credentials to automatically authenticate when
necessary.

Tip: To reduce possible errors, in your algorithm code use the specific type when
defining variables instead of using the any type. For example, instead of let myValue:
any; use let myValue: number;. For more on types, see Everyday Types (external
link).

Open an existing embedded algorithms project

If you have already created an embedded algorithms project, you can open it by clicking the
Open Project button when you first open the extension in Visual Studio Code or at any time by
opening the folder for that project.

RapidResponse Embedded Algorithms Guide 85

Creating a new embedded algorithms project
 Stub code
Stub code is generated for each algorithm in the namespace you selected when you created a
new embedded algorithms project. All of the inputs and outputs defined for the algorithm are
included in the stub code. The stub also throws an error to ensure that it isn't ever used for the
algorithm.
Each algorithm has two files created for it:
l .ts file—this is the entry function for the algorithm and is the file that you will edit.

l [Link] file—this defines all of the types for the algorithm based on its schema. Do not edit
[Link] files that you have not created and that are automatically generated to contain the

86 RapidResponse Embedded Algorithms Guide

CHAPTER 5: Writing code for an embedded algorithm
 dependency type definitions.

Family calculations
You can group records into families and perform embedded algorithms on the groups instead of
running the algorithm on each individual record. You might want to do this to implement supply
chain logic such as grouping a set of parts that are produced on the same resource that you
want calculated results for the set at one time. In addition to making more efficient use of the
algorithm, performance can also be improved by reducing redundancy for records with shared
dependencies. For example, if record A and record B use the same data, then reducing the
number of smaller calculations by grouping them into a single query can reduce calculation
overhead. As with all algorithms, depending on their design and purpose, performance should
be measure and an appropriate strategy applied. For some cases, splitting the calculation into
multiple smaller algorithms instead could provide better performance. See "Using multiple
algorithms" on page 109.
Each record in the family is called a family member and the family leader is a record that all
members point to that identifies them as members of the same family.
Families are implemented using extension fields where each extension record points to the
owing record that calculates it.

Setting up a family calculation

Two steps are required to set up a family calculation

RapidResponse Embedded Algorithms Guide 87

Family calculations
 Step 1: Create a set field
Create a embedded algorithm reference field you can set it to auto-generate its corresponding
set field. The records in the set field are a group (family) and calculations on the field are applied
to all records in it. See "Reference and set fields" on page 56.

Step 2: Create an extension field

Create an embedded algorithm field on the algorithm's owning table and specify a path from
the embedded algorithm field back to the owning table. The path defined in step 1 should be
this owner path. The embedded algorithm field is now an extension field on the owning table
and the set calculated in step 1 is treated as a family with calculations performed on the family
instead of one calculation per record in the array. See "Extension fields" on page 58.
The stub code generated by a family calculation setup includes two algorithms in it:
l Family Grouping Algorithm: this code defines the members of the family by pointing
each member's reference field to its leader.
l Family Calculation Algorithm: this code defines and executes the calculations on the
family using the extension field. This calculation is triggered once per family.

See "Stub code" on page 86.

88 RapidResponse Embedded Algorithms Guide

CHAPTER 5: Writing code for an embedded algorithm
Editing algorithm code
The embedded algorithm stub code is in the project folder generated when you start a new
project.

1. Open the project folder for the project name you specified when creating the algorithm
project. See "Creating a new embedded algorithms project" on page 84.
2. Open src > algorithms.
3. Open the algorithm .ts file you want to edit.
4. Edit the algorithm code.

Cautions:
l Do not modify any of the automatically generated .[Link] files that hold the dependency
type definitions.
l The embedded algorithm stub includes the .rapidresponse directory. This directory
should never be modified.
l All date fields used in embedded algorithms are set to the UTC (Coordinated
Universal Time) time zone. However, Javascript automatically uses your local system
time when executing so you need to account for this when using Date methods
impacted by time zones, such as yesterday, or minute. For more on UTC methods, see
Date components and time zones (external site).

Note: When compiling projects that were created with Embedded Algorithm tools that
are versions earlier than EA 2.5.0, you might encounter errors in the code that have to be
fixed. This is because the TypeScript compiler now has different code expectations.

RapidResponse Embedded Algorithms Guide 89

Editing algorithm code
 Code library modules
Embedded algorithms can use the following modules to work with date, calendar, and unit of
measure data in RapidResponse.

Modules:
• calendar-math—Use this module to perform date arithmetic using RapidResponse calendars.
See "calendar-math library module" on page 91.
• date-helpers—Use this module to manipulate dates. See "date-helpers library module" on
page 96.
• unit-of-measure—Use this module to apply unit of measure conversions to specific values. See
"unit-of-measure library module" on page 100.
These modules are publicly available and you can read more about them on the Kinaxis
organization npm page.

Download a module
l In the project folder of your Embedded Algorithms project, run the npm install command:
npm install @kinaxis/name-of-module.
For example, to install the calendar-math module, the command is:
npm install @kinaxis/calendar-math

Note: For more on how to use the npm install command, see npm-install.

90 RapidResponse Embedded Algorithms Guide

CHAPTER 5: Writing code for an embedded algorithm
calendar-math library module
The calendar-math module provides helper functions to perform date arithmetic using
RapidResponse calendars.
To use RapidResponse calendars in an embedded algorithm, the algorithm must have
appropriate dependencies on the Calendar and CalendarDate tables.
For more on RapidResponse calendars, see Calendar tables in the Data Model and Algorithm
Guide available at the Documentation Center.

Notes:
l Input data from RapidResponse in the format of Date is automatically passed into
your algorithm code as JavaScript Dates. If you want to create your own date in
external code, use the standard constructor to create a JavaScript Date object
(external link).
l Valid date ranges are from January 1, 1970 - December 31, 2099.

Types
The calendar-math modules contains the following types:

Type Description
Calendar A collection of dates that define the intervals of the calendar. See "Calendar type" on page 92.

CalendarDate A date in a calendar that represents the start of an interval. See "CalendarDate type" on page 92.

RapidResponse Embedded Algorithms Guide 91

Code library modules
 Calendar type
A calendar contains all of the dates that define the intervals of a calendar in RapidResponse such
as Week, Month, Workday, or Everyday.
The Calendar type has the following property:

Property Type Description

Dates CalendarDate[] An array of CalendarDates that define the intervals
of the specified calendar. For example, the Month
calendar contains a CalendarDate for the first day
of each month.

CalendarDate type
The CalendarDate type has the following property:

Property Type Description

Value Date The JavaScript Date value that defines the starting point of the associated calendar’s
intervals.

calendar-math functions
The calendar-math module implements the following functions:

Function Description
addCalendarToDate Offsets the date by a specified number of calendar intervals. See
"addCalendarToDate function" on page 93.

subtractDates Calculates the number of intervals in the calendar between two specified dates. See
"subtractDates function" on page 94.

These functions follow the RapidResponse data arithmetic rules. For more on RapidResponse
calendars, see Calendars and date arithmetic in the Resource Authoring Guide available at the
Documentation Center.

92 RapidResponse Embedded Algorithms Guide

CHAPTER 5: Writing code for an embedded algorithm
addCalendarToDate function
Using RapidResponse date arithmetic rules, this function offsets a date by a specified number of
calendar intervals.

Syntax
addCalendarToDate(date, amount, calendar)

Parameter Type Description

date Date The date to offset.
Using [Link] or [Link] returns the original date as the value.
Using an invalid date returns the value [Link].

amount Number The number of calendar intervals to offset the date by.
Adding 0 returns the beginning of the specified date's current interval for the
specified calendar.

calendar Calendar The calendar to use for the function.

This value is optional. If no calendar is specified, or if the calendar has no dates,
amount is interpreted in days.

Returns

Type Description
Date The date calculated by adding the specified amount intervals in the specified calendar to the
date to offset.
If the result is less than the first valid date in the calendar, [Link] is returned.
If the result is greater than the last valid date in the calendar, [Link] is returned.

Examples

To return Do this
First day of next week Use the Week calendar and specify amount as 1.

First day of the previous week Use the Week calendar and specify amount as -1.

First day of the date’s week Use the Week calendar and specify amount as 0.

First day of the date’s month Use the Month calendar and specify amount as 0.

RapidResponse Embedded Algorithms Guide 93

Code library modules
 subtractDates function
Using RapidResponse date arithmetic rules, this function calculates the number of intervals in a
specified calendar between two specified dates.

Syntax
subtractDates(date1, date2, calendar)

Parameter Type Description

date1 Date The first date.

date2 Date The second date.

calendar Calendar The calendar to use for the function. This value is optional.
If no calendar is specified or if the calendar has no dates, amount is interpreted in
days.
If the calendar has only one date, the result will be 65535.

Returns

Type Description
Date The span of time between date1 and date2 in intervals of the specified calendar.
If any of the following is true:
l date1 or date2 are invalid
l date1 or date2 are equal to [Link], [Link], or
[Link]
l the result of the calculation is outside of the bounds of the specified
calendar
then the result will be 65535 (if date1 is larger) or -65535 (if date2 is larger).
If the calendar only has one date, then the result will always be 65535.

Example
Using the following dates and an object Month to represent the RapidResponse Month
calendar:
const date1 = new Date("2020-09-14T00:00:00.000Z");
const date2 = new Date("2020-06-12T00:00:00.000Z");

Calling the subtractDates function as follows returns a value of 3 (3 months):

94 RapidResponse Embedded Algorithms Guide

CHAPTER 5: Writing code for an embedded algorithm
subtractDates(date1, date2, Month);

RapidResponse Embedded Algorithms Guide 95

Code library modules
 date-helpers library module
The date-helpers module provides helper functions and constants to create, convert, and
validate dates. In addition, you can use it to check whether or not a date is one of the special
constants. The calendar-math module uses the constants and functions from this module. See
"calendar-math library module" on page 91.

Constants
The date-helpers module contains the following constants

Constant Type Description

PAST_DATE Date Represents a date at some time in the past.

FUTURE_DATE Date Represents a date at some time in the future.

UNDEFINED_DATE Date Represents an invalid date.

FIRST_VALID_DATE Date Represents the earliest valid date that RapidResponse can display.

FIRST_VALID_DATE_VALUE Number Represents the numeric value for the FIRST_VALID_DATE constant.

LAST_VALID_DATE Date Represents the latest valid date that RapidResponse can display.

LAST_VALID_DATE_VALUE Number Represents the numeric value for the LAST_VALID_DATE constant.

Notes:
l The constants PAST_DATE, FUTURE_DATE, UNDEFINED_DATE can also be accessed
using their corresponding aliases: [Link], [Link], and [Link].
l Valid date ranges are from January 1, 1970 - December 31, 2099.

For more on RapidResponse date constants, see Date constants in the Data Model and
Algorithm Guide available at the Documentation Center.

96 RapidResponse Embedded Algorithms Guide

CHAPTER 5: Writing code for an embedded algorithm
date-helpers functions
The date-helpers module implements the following functions:

Function Descripton
createDate Creates a new Date object using the number of days since January 1, 1970. See "createDate
function" on page 97.

dateToDays Converts a Date object to number of days since January 1, 1970. See "dateToDays function" on
page 98.

clipDate Checks if a date is within the RapidResponse date boundaries. If not, it converts the Date
object to the appropriate constant value. See "clipDate function" on page 98.

isDateConstant Determines if a Date object has the value of a date constant. See "isDateConstant function" on
page 99.

createDate function
Creates a new Date object using the number of days since January 1, 1970.

Syntax
createDate(numberOfDays)

Parameter Type Description

numberOfDays Number The number of days since January 1, 1970.

Returns

Type Description
numberofDays The number of days after January 1, 1970.

RapidResponse Embedded Algorithms Guide 97

Code library modules
 dateToDays function
Converts a Date object to number of days since January 1, 1970.

Syntax
dateToDays(date)

Parameter Type Description

date Date The date to convert.

Returns

Type Description
Number The days between the date and January 1, 1970.
Invalid dates return a value of 65534.

clipDate function
Checks if a date is within the RapidResponse date boundaries. If not, it converts the Date object
to the appropriate constant value.
For example, a date greater than the LAST_VALID_DATE constant will be converted to the
FUTURE_DATE constant.

Syntax
clipDate(date)

Parameter Type Description

date Date The date to check, and if required, convert to a constant value.

Returns

Value Type Descripton

date Date If date is within the range [FIRST_VALID_DATE, LAST_VALID_DATE].

PAST_DATE Date If date is less than FIRST_VALID_DATE.

FUTURE_DATE Date If date is greater than LAST_VALID_DATE.

UNDEFINED_DATE Date If date is invalid.

98 RapidResponse Embedded Algorithms Guide

CHAPTER 5: Writing code for an embedded algorithm
isDateConstant function
Determines if a Date object has the value of a date constant.

Syntax
isDateConstant(date)

Parameter Type Description

date Date The date to check.

Returns

Type Description
true If date has the value of a date constant (PAST_DATE, FUTURE_DATE, or UNDEFINED_DATE).
Otherwise returns a value of false.

RapidResponse Embedded Algorithms Guide 99

Code library modules
 unit-of-measure library module
The unit-of-measure module provides helper functions for applying unit of measure
conversions.
Base units of measure in your system are defined in the Control Tables or Control Sets
workbooks. See Configuring unit conversions in the RapidResponse Administration Guide
available at the Documentation Center.

Types
The unit-of-measure modules contains the following types:

Type Description
ControlSet A grouping of RapidResponse control table settings. See "ControlSet type" on
page 100.

UnitOfMeasure Defines the magnitude of a RapidResponse quantity with respect to the specified
unit of measure. See "UnitOfMeasure type" on page 101.

ItemSpecificUOMConversion Specific unit of measure defined for an individual item instead of for all items.
This overrides the standard conversion rate. See "ItemSpecificUOMConversion
type" on page 101.

NumberUoM A converted quantity with its associated unit of measure. See "NumberUoM
type" on page 101.

ControlSet type
The ControlSet type contains the name of the group of RapidResponse control table settings
you want to use to define unit of measure [Link] use RapidResponse control sets in an
embedded algorithm, the algorithm must have appropriate dependencies on the ControlSet
[Link] ControlSet type has the following property:

Property Type Description

Value String The name of the control set.

For more on control tables and control sets, see Control tables and control sets in the Data
Integration Guide available at the Documentation Center.

100 RapidResponse Embedded Algorithms Guide

CHAPTER 5: Writing code for an embedded algorithm
UnitOfMeasure type
The UnitOfMeasure type defines the magnitude of a RapidResponse quantity with respect to the
base unit of measure. To use RapidResponse unit of measure in an embedded algorithm, the
algorithm must have appropriate dependencies on the UnitOfMeasure table. See "Global
dependencies" on page 41. The UnitOfMeasure type has the following properties:

Property Type Description

Value String The name of the unit of measure.

BaseConversion Number The factor to use when converting from the base unit of measure.

ControlSet ControlSet The control set for the unit of measure.

ItemSpecificUOMConversion type
The specific unit of measure defined for an individual item instead of for all items. This overrides
the standard conversion rate. The ItemSpecificUOMConversion type has the following
properties:

Property Type Description

UnitOfMeasure UnitOfMeasure The unit of measure to override.

Factor Number The factor to use when converting from the base unit of measure.

NumberUoM type
A converted quantity with its associated unit of measure. This type serves as both input and
output for the unit-of-measure conversion functions, enabling easy reconversion of the results of
helper functions. See "ConvertUoM_Quantity function" on page 103 and "ConvertUoM_Money
function" on page 106.
The NumberUoM type has the following properties:

Property Type Description

Number Number The converted quantity.

UnitOfMeasure UnitOfMeasure The unit of measure for the Number property.

IsMoney Boolean Indicates whether the Number property is a money

value.

ItemSpecificUoM ItemSpecificUOMConversion or Optional array of units of measure to override when

undefined doing conversions.

RapidResponse Embedded Algorithms Guide 101

Code library modules
 unit-of-measure functions
The unit-of-measure module implements the following functions. The embedded algorithm
must have the following global dependencies defined to use these functions:
l [Link]
l [Link]
l [Link]
l [Link]

Function Description
GetTargetUoM Retrieves a specific unit of measure from the global dependencies. See "GetTargetUoM
function" on page 102.

ConvertUoM_ Converts a quantity value from a specified unit of measure to another unit of measure. See
Quantity "ConvertUoM_Quantity function" on page 103.

ConvertUoM_ Converts a money value from a specified unit of measure to another unit of measure. See
Money "ConvertUoM_Money function" on page 106.

Note: The base and target UOM values must use the same control set.

GetTargetUoM function
Retrieves a specific unit of measure.

Syntax
GetTargetUoM(tables, uom, controlSet)

Parameter Type Description

tables Tables The global dependency tables argument passed to the embedded algorithm.

uom String Represents the target unit of measure. This parameter corresponds to the Value
string field in the UnitOfMeasure table.

controlSet ControlSet The control set related to the target unit of measure. This parameter
corresponds to the reference key field in the UnitOfMeasure table.

102 RapidResponse Embedded Algorithms Guide

CHAPTER 5: Writing code for an embedded algorithm
Returns

Type Description
NumberUoM A UnitOfMeasure record that matches the uom and controlSet parameters. If a unit of measure
cannot be found based on the specified uom and control set parameters, a value of undefined is
returned.

Example
In the embedded algorithm, retrieving a unit of measure for “Milliliter” in the Volume control set
returns the following:
{
Value: "Milliliter",BaseConversion: 0.001,ControlSet: { Value:
"Volume" }
}

ConvertUoM_Quantity function
Converts a quantity value from a specified unit of measure to another unit of measure.

Syntax
ConvertUoM_Quantity(uom, tables, targetUoM)

Parameter Type Description

uom NumberUoM A quantity with an associated unit of measure to convert.

tables Tables The global dependency tables argument passed to the embedded algorithm.

targetUoM String The target unit of measure to convert the uom parameter into.
To successfully convert the quantity, a corresponding value in
[Link] is matched to the string. If there is value defined for
ItemSpecificUoM, then [Link] is first searched for a value
and if found, this value overrides the target.
If no value is found in [Link] (if applicable) or
[Link], then the Number property of the return value
equals NaN.

Returns

Type Description
NumberUoM The converted quantity with its associated unit of measure.

RapidResponse Embedded Algorithms Guide 103

Code library modules
 Note: The Number property of the return value equals NaN if the conversion ratio of the
base or target unit of measure is less than or equal to [Link] this function is called with
[Link] === true, an Error is thrown.

104 RapidResponse Embedded Algorithms Guide

CHAPTER 5: Writing code for an embedded algorithm
Example
To convert 5 Liters in Milliliters, the NumberUoM object must first be defined in the algorithm as
follows.
// Create input
const volumeControlSet = { Value: "Volume" };
const uom = {
Number: 5,
UnitOfMeasure: GetTargetUoM(tables, "Liter", volumeControlSet),
IsMoney: false
};
const targetUoM = "Milliliter";
// Now call the function
ConvertUoM_Quantity(uom, tables, targetUoM);

In the embedded algorithm, the following is returned:

{
Number: 5000,
UnitOfMeasure: Value: "Milliliter",
BaseConversion: 0.001,
ControlSet: {Value: "Volume"}
},
IsMoney: false
}

RapidResponse Embedded Algorithms Guide 105

Code library modules
 ConvertUoM_Money function
Converts a money value from a specified unit of measure to another unit of measure. Unlike
quantity, money values are only converted on a per unit cost basis. Let's assume we have a part
named 'Bike' with quantity '24' each with an average selling price of '2 USD'. If we wanted to
convert the quantity value (24) to Dozens, we would return 2 Dozens (2 dozen units is equal to
24 units). If we wanted to convert the money value (2USD) to Dozens we would return 24 USD (1
dozen units is worth 24USD).

Syntax
ConvertUoM_Money(uom, tables, targetUoM)

Parameter Type Description

uom NumberUoM A money value with an associated unit of measure to convert.
Note: Here [Link] = True

tables Tables The global dependency tables argument passed to the embedded algorithm.

targetUoM String The target unit of measure to convert the uom parameter into.
To successfully convert the money value, a corresponding value in
[Link] is matched to the string. If there is value defined for
ItemSpecificUoM, then [Link] is first searched for a value
and if found, this value overrides the target.
If no value is found in [Link] (if applicable) or
[Link], then the Number property of the return value
equals NaN.

Note: If this function is called with [Link] === false, an Error is thrown.

Returns

Type Description
NumberUoM A converted money value with its associated unit of measure.
Note: Here [Link] = True

106 RapidResponse Embedded Algorithms Guide

CHAPTER 5: Writing code for an embedded algorithm
Example
To convert 2USD to Dozens, the NumberUoM object must first be defined in the algorithm as
follows:
// Create input
const countControlSet = { Value: "Count" };
const uom = {
Number: 2,
UnitOfMeasure: GetTargetUoM(tables, "Single", countControlSet),
IsMoney: true
};
const targetUoM = "Dozen";
// Now call the function
ConvertUoM_Money(uom, tables, targetUoM);

In the embedded algorithm, the following is returned:

{
Number: 24,
UnitOfMeasure: Value: "Dozen",
BaseConversion: 12,
ControlSet: {Value: "Count"}
},
IsMoney:true
}

In the embedded algorithm, the following is returned:

{
Number: 24,
UnitOfMeasure: {
Value: "Dozen",
BaseConversion: 12,
ControlSet: {Value: "Count"}
},
IsMoney: true
}

RapidResponse Embedded Algorithms Guide 107

Code library modules
 The value returned is 24USD. The currency in this example was identified for context but not
included in the actual code. This is because embedded algorithms convert currencies into the
base currency defined, which might not be USD.

108 RapidResponse Embedded Algorithms Guide

CHAPTER 5: Writing code for an embedded algorithm
Updating an embedded algorithm
If you have made changes to the data model schema used by embedded algorithms, you need
to update the algorithm code accordingly. Run the Update Project command to ensure that the
algorithm code contains the latest data model schema. All of the existing algorithm files are
updated and code stubs for new algorithms are generated. Any algorithms deleted in the data
model are identified and you have the option to delete the code for the missing algorithms. See
"Extension commands" on page 80.

1. In your open embedded algorithms project, click the Embedded Algorithms extension
tab .
2. Click Update Project.

Depending on what changes have been made to the data model schema, algorithms should be
tested to ensure that the data model changes did not break or alter the expected algorithm
results. See "Testing and debugging embedded algorithms" on page 113.

Note: After changes have been made to the data model schema, the RapidResponse
server must be restarted. If you're only making changes to the embedded algorithm
code, the server doesn't need to be restarted.

Note: If an algorithm is renamed in the data model, it might be detected as a deletion.

Using multiple algorithms

When you create an embedded algorithm, it implements a single function that can compute
multiple results. Depending on the requirements of the business solution you are creating, you
might create multiple algorithms that work in tandem. For example, if the output data you
require used the same input, then it is recommended that a single algorithm is used to
implement your solution to ensure better performance on the RapidResponse server.
If the same input data is used to generate multiple outputs, it is recommended that you use a
single algorithm to implement that solution. This ensures better performance in the
RapidResponse server. For example if data needs to be sorted at different levels of output, then
the sort function should be included in the same algorithm as the other calculations.
If the input and outputs for your solution can be split into subsets or if a subset of the
calculations changes less often that other calculations, multiple algorithms might provide better
performance. For example, if data needs to be sorted once and those results are used in multiple
other algorithms, then the sort function should have its own algorithm to enable a global sort
calculation.

RapidResponse Embedded Algorithms Guide 109

Updating an embedded algorithm
 Recursive algorithms
When you use multiple algorithms in a solution, each algorithm can produce a set of
independent results, or you can include recursive algorithms in your solution. Recursive
algorithms use the calculated results of the same algorithm as input. This input must be the
results of calculations that take place on data different from the calculation you are actively
running.
For example, you create an algorithm that calculates the cumulative lead time on a part by
adding the lead time for the part to the lead times for all of the components for that part. The
diagram below outlines how the lead times are calculated.
When you run the algorithm on Part A, the algorithm also computes the lead times for Parts B, C,
and H. The results for Part A depend on the results for Parts B, C, and H.

110 RapidResponse Embedded Algorithms Guide

CHAPTER 5: Writing code for an embedded algorithm
Publishing an embedded algorithm
After you completed editing the algorithm code and have tested that it works as expected, you
must publish the project. The Publish Project command generates the algorithms in the project
and uploads the code to the connected RapidResponse data server. The algorithms project must
be published to test it in RapidResponse. See "Test an algorithm using a worksheet" on page
114.
For users to access the embedded algorithm(s), it must be published to the test RapidResponse
server and then exported to the production RapidResponse server in an integration package. See
"Packaging and deploying an embedded algorithm" on page 123.

1. In your open embedded algorithms project, click the Embedded Algorithms extension
tab .
2. Click Publish Project.
3. When prompted to make the published algorithms the active implementations, select Yes.

Note: A published embedded algorithms project might not upload if there is an issue
with an algorithm in that namespace. It is recommended that you validate the algorithms
before publishing. See "Validate your algorithm" on page 118.

Note: Only one RapidResponse server can connect to the algorithms agent to run
embedded algorithms. For more on the algorithms agent, see the RapidResponse
Administration Guide.

RapidResponse Embedded Algorithms Guide 111

Publishing an embedded algorithm
CHAPTER 6: Testing and debugging
embedded algorithms
Test an algorithm using a worksheet 114
Validate your algorithm 118
Trigger the algorithm 118
Configure warning settings 119
Review error dumps 122

In Visual Studio Code, the Embedded Algorithms extension enables you to debug:
l A specified namespace
l Multiple namespaces at the same time.
l The same namespace as other users at the same time. Two developers on separate
machines can debug the same namespace simultaneously.

In addition to the standard debugging capabilities in Visual Studio Code, you can also test
embedded algorithms in the following ways:
l Test the embedded algorithm with a RapidResponse worksheet to confirm it returns the
expected results. You can run a debug session in Visual Studio Code and review the
algorithm execution in real-time or publish the algorithm and debug any error dumps that
are generated. See "Test an algorithm using a worksheet" on page 114.
l Run the algorithm on a single record to review and validate the algorithm logic. See "Trigger
the algorithm" on page 118.
l Generate a static compile of the algorithm code to review and validate the algorithm logic.
See "Validate your algorithm" on page 118.

RapidResponse Embedded Algorithms Guide 113

 l Configure memory settings to ensure that the algorithm doesn't use more memory than
expected. See "Configure warning settings" on page 119.
l Download and review error dumps from the RapidResponse server to troubleshoot
potential errors after the algorithm has been deployed. See "Review error dumps" on page
122.

Test an algorithm using a worksheet

You can use a RapidResponse worksheet to confirm that an embedded algorithm returns
expected results. When the worksheet is opened, the algorithm is triggered to run on each
record in the owning table for the algorithm that are visible with the current filter settings in the
worksheet.
Using a worksheet provides you with more control over what inputs and outputs are used in the
algorithm by what data settings are applied when the worksheet is opened and how the
worksheet is designed. See "Designing the test worksheets" on page 116.
You can use a worksheet to test an algorithm by:
l Publishing the algorithm and then opening the worksheet. The published algorithm code
runs and any errors generate an error log that you can review. See "Review error dumps" on
page 122.
This method simulates how the algorithm will perform on a production system. See "Test a
published algorithm using a worksheet" on page 114.
l Starting a debug session in Visual Studio Code and then opening the worksheet. The
algorithm code on your development system runs. See "Debug an algorithm using a
worksheet" on page 115.

Note: Only embedded algorithm fields are valid output fields for an algorithm.

Test a published algorithm using a worksheet

It is recommended that you test the results using different filters and all of your data to assess
the algorithm performance.

1. Publish the algorithm code. See "Publishing an embedded algorithm" on page 111.
2. Open the workbook you created from the Recent Activity pane or the Explorer pane.
3. Specify the data settings you want to test with.
4. Click the output worksheet tab in the workbook.

Note: The algorithm must be published before it can be tested without the debugging
features in the Embedded Algorithms extension in Visual Studio Code.

114 RapidResponse Embedded Algorithms Guide

CHAPTER 6: Testing and debugging embedded algorithms
Debug an algorithm using a worksheet
When debugging, only one calculation is run at a time so it is recommended that you design the
output worksheet to filter to a single record. Use a combination of data settings and worksheet
filter settings to filter the data. For more on how to filter data in a worksheet, see Authoring and
managing filters in the the RapidResponse Resource Authoring Guide (Java client).

1. Start debugging in Visual Studio Code.

2. In RapidResponse, open the workbook you created from the Recent Activity pane or the
Explorer pane.
3. Specify data settings that return a single record in the output worksheet, for example a
specific part and site.
4. Click the output worksheet tab in the workbook.

Caution: When debugging an algorithm, do not use filters that return large sets of data
such as All Parts, All Items, or All sites because they can affect performance of the server.

RapidResponse Embedded Algorithms Guide 115

Test an algorithm using a worksheet
 Designing the test worksheets
Create a simple output worksheet to view the data generated by the algorithm. In addition, you
can add input worksheets that display the data used by the algorithm in its calculations. Using
both input and output worksheets help you to confirm that the algorithm is working as
expected.

Create a new test workbook and worksheets

These steps add one input and one output worksheet in the test workbook. Depending on how
your solution is designed, you might include more worksheets.

1. On the File menu, point to New and then click Workbook.

2. In the New Workbook dialog box, click the General tab.
3. In the Name box, type a unique name.
4. In the Type area, ensure Standard is selected.
5. Click the Worksheets tab.
6. Click New and then click Worksheet (Table-based).
7. In the New Worksheet dialog box, click the General tab.
8. In the Name box, type “Output”.
9. In the table list, select the output table for the embedded algorithm.
This is the table that contains the embedded algorithm field(s) that the algorithm outputs
to.
10. On the Columns tab, click Add Fields.
11. In the Add Fields dialog box, select the output field for the algorithm and click Add.
12. If required, repeat step 11 to add more output fields to the worksheet.
13. Click OK twice.
14. Optionally you can follow the next steps to add an input worksheet or click OK to exit the
Workbook Properties dialog box.

Add an input worksheet

1. In the workbook properties for the test workbook you created, click the Worksheets tab.
2. Click New and then click Worksheet (Table-based).
3. In the New Worksheet dialog box, click the General tab.
4. In the Name box, type “Input”.
5. In the table list, select the owning table for the embedded algorithm.
6. On the Columns tab, click Add Fields.
7. In the Add Fields dialog box, select an input field for the algorithm and click Add.
8. If required, repeat step 7 to add more input fields to the worksheet.
9. Click OK three times to exit all dialog boxes.

116 RapidResponse Embedded Algorithms Guide

CHAPTER 6: Testing and debugging embedded algorithms
 Note: The worksheet names are suggestions.

Test a published algorithm on a specific record

When you test an algorithm by triggering it, a maximum of ten records display in the owning
record list. To test the algorithm on an owning record in the table that does not display in this
list, you must test the algorithm using a worksheet that has been filtered to display on the
records you want to test.

1. Start debugging in Visual Studio Code.

2. In RapidResponse, use a workbook filter to isolate the records you want to use in the
algorithm calculation.
3. Refresh or modify the workbook filter to trigger the algorithm to run.

RapidResponse Embedded Algorithms Guide 117

Test an algorithm using a worksheet
 Validate your algorithm
One way to check your algorithm is to validate the code using the Validate Algorithms command
in the Embedded Algorithms extension. This generates a static compile of the code for the
embedded algorithms in your project. Any errors are highlighted in the terminal.

Trigger the algorithm

You can test the algorithm by triggering it to run in a scenario and on a record that you specify.
This method doesn't require a RapidResponse worksheet and is a quick way to review the
algorithm code, including when the specific record tests a specific use-case that you are
designing for.

Debug the algorithm using any one record

To run an algorithm within Visual Studio code to review the algorithm logic, run the Trigger
Algorithm command. The command runs the algorithm in a scenario and with the owning record
that you specify. Only a maximum of 10 records display in the owning records list. To use an
owning record from the table that is outside of this list, see "Test a published algorithm on a
specific record" on page 117.

1. In the list of extension commands, click Trigger Algorithm.

2. Select the scenario to execute the algorithm in.
3. Select the owning record from the owning table. This record is used in the algorithm
calculation.

Note: To test how the algorithm runs on multiple records, it's better to test the
algorithm in a RapidResponse worksheet. See "Test an algorithm using a worksheet" on
page 114.

118 RapidResponse Embedded Algorithms Guide

CHAPTER 6: Testing and debugging embedded algorithms
Configure warning settings
To ensure that your embedded algorithm will execute efficiently for users, you can configure
warnings to detect the following:
l When the size of a compiled algorithm exceeds a defined threshold. The default size is 8
MB.
l When the data requested by the algorithm calculations exceeds a defined size threshold.
The default size is 250 MB.
l When the record count of any table used by the algorithm exceeds a defined size threshold.
The warning message identifies the specific table that triggered the warning. The default
number of records is 200K.
l When the total record count across all tables used by the algorithm exceeds a defined size
threshold. Each table and its record count is reported in the warning message along with
the total record count. The default number of records is 1M.
l When the memory used by a single calculation of an algorithm exceeds a defined memory
threshold. The default is 2048 (2 GB).
In addition to setting a threshold for the memory that algorithms use, you can also specify
how frequently the memory usage is tracked. See "Configure the memory usage interval"
on page 121.

These warnings display with the existing logs in the Visual Studio Code console.

When a warning is triggered

If your algorithm triggers a warning, do one or more of the following:
l Review your code, including your data model schema.
Large algorithms can result in slower calculations. It is recommended that you simplify the
algorithm code. If the code cannot be simplified, then you can modify the algorithm size
threshold.
l Review the tables used by the algorithm.
Assess if the current owning table and dependency tables used by the algorithm are the
most efficient paths to the required data. You might consider using other tables with a
more direct path to the required data or suitable tables that have fewer records.
l Assess if adding a dependency filter might improve algorithm performance.
Dependency filters refine the data from dependency tables used by the algorithm. See
"Identify if dependency tables should be filtered" on page 50.
l If the memory requirement of the algorithm exceeds what is available in your system,
contact your RapidResponse administrator to have Kinaxis deploy the code in an
environment with the appropriate resources.

RapidResponse Embedded Algorithms Guide 119

Configure warning settings
 Configure the compiled algorithm size threshold
1. In Visual Studio Code click File.
2. Select Preferences and then click Settings.
3. Click Extensions to expand the list and then click Embedded Algorithms Developer
Tools.
4. For Rapid Response > Embedded Algorithms > Algorithm Code Size Warning
Threshold MB, type a number. This value is in MB.
The default threshold is 8 MB.
5. Close the Settings tab.

Configure the request size threshold

1. In Visual Studio Code click File.
2. Select Preferences and then click Settings.
3. Click Extensions to expand the list and then click Embedded Algorithms Developer
Tools.
4. For Rapid Response > Embedded Algorithms > Request Size Warning Threshold
MB, type a number. This value is in MB.
The default threshold is 250 MB.
5. Close the Settings tab.

Configure the record count threshold for a table requested by the algorithm
This applies to any single table used by the algorithm. The warning message identities the name
of the table that has exceeded the defined record count threshold.

1. In Visual Studio Code click File.

2. Select Preferences and then click Settings.
3. Click Extensions to expand the list and then click Embedded Algorithms Developer
Tools.
4. For Rapid Response > Embedded Algorithms > Request Table Record Count
Warning Threshold, type a number. This value is in number of records.
The default threshold is 200K records.
5. Close the Settings tab.

Configure the record count threshold across all tables requested by the
algorithm
1. In Visual Studio Code click File.
2. Select Preferences and then click Settings.

120 RapidResponse Embedded Algorithms Guide

CHAPTER 6: Testing and debugging embedded algorithms
3. Click Extensions to expand the list and then click Embedded Algorithms Developer
Tools.
4. For Rapid Response > Embedded Algorithms > Request Total Tables Record Count
Warning Threshold, type a number. This value is in number of records.
The default threshold is 1M records.
5. Close the Settings tab.

Configure the memory warning threshold

1. In Visual Studio Code click File.
2. Select Preferences and then click Settings.
3. Click Extensions to expand the list and then click Embedded Algorithms Developer
Tools.
4. For Rapid Response > Embedded Algorithms > Debugging: Worker Memory
Warning Threshold MB, type a number. This value is in MB.
The default threshold is 2048 (2 GB).
5. Close the Settings tab.

Configure the memory usage interval

1. In Visual Studio Code click File.
2. Select Preferences and then click Settings.
3. Click Extensions to expand the list and then click Embedded Algorithms Developer
Tools.
4. For Rapid Response > Embedded Algorithms > Debugging: Worker Memory Usage
Check Interval Ms, type a number. This value is in milliseconds.
The default interval is 30000 (30 seconds).
5. Close the Settings tab.

RapidResponse Embedded Algorithms Guide 121

Configure warning settings
 Review error dumps
When an algorithm runs on the RapidResponse server and an error is generated, the error is
logged. Depending on whether you have direct access to the error dump file, you can either
download or import the log.
Downloaded and imported error dumps display in the Error Dumps section below the available
extension commands.

Download the error dump

This command allows the dump file to be downloaded and imported from the RapidResponse
server directly into Visual Studio Code.
l In the list of extension commands, click Download Error Dump.

Import the error dump

For production instances of RapidResponse, import error dump files downloaded from the
Embedded Algorithm Details and Log workbook.

1. In the list of extension commands, click Import Error Dumps.

2. Select the error dump file(s) to import and click Import Dumps.

Note: Prior to Embedded Algorithms 2.1.0, error dump files would have to be manually
imported after download from RapidResponse.

122 RapidResponse Embedded Algorithms Guide

CHAPTER 6: Testing and debugging embedded algorithms
CHAPTER 7: Packaging and deploying an
embedded algorithm
Migrating embedded algorithms 124

After an embedded algorithm has been tested and validated on a test system, it must be
migrated along with its associated data model changes to the production system where it is
deployed to users. Once the migration package has been successfully imported into the
production system, depending on how the algorithm was designed, it will run when triggered.
When migrating embedded algorithm code in integration packages, you have the option of only
importing code changes without importing unrelated data model changes. This updates the
algorithm and enables you to exclude data model changes that don't affect the algorithm or are
not ready for migration. To import the code-only changes, your import system must have the
same embedded algorithms with the same defined inputs and outputs as the integration
package. For more, see the RapidResponse Administration Guide.

Note: If your system is the On-Demand RapidResponse service, you can only export
integration packages. To import a integration package, you will need to work with Kinaxis
Customer Support.

RapidResponse Embedded Algorithms Guide 123

 Migrating embedded algorithms
Embedded algorithms are exported to a production system using an integration package (.ipk).
The integration package migrates integration settings including:
l Data model namespaces—all namespaces in the system.
l Data sources and mappings—all data source and mapping files from a scenario you
specify.
l Embedded algorithms—all algorithms from a namespace you specify, including the
published algorithm code on that RapidResponse data server.
For a full list of the integration settings included in an integration package, see Migrating
data integration settings in the RapidResponse Administration Guide.

In systems using the On-Demand RapidResponse service, Kinaxis Customer Support will work
with you to move your data integration settings to the planning server. The package is imported
during a defined maintenance window.
If you are using an On-Premise RapidResponse system, refer to the RapidResponse Data
Integration Guide for details on how to migrate resources and settings between systems. See
About migrating resources and settings in the RapidResponse Administration Guide.

Note: Optionally, if you have also created RapidResponse resources to support the
embedded algorithm, you can use an application package (.kpk) to migrate the
algorithms, data model changes, and resources to the production system. See Migrating
changes together in application packages in the RapidResponse Administration Guide.

124 RapidResponse Embedded Algorithms Guide

CHAPTER 7: Packaging and deploying an embedded algorithm
World Headquarters

3199 Palladium Drive

Ottawa, Ontario
Canada K2T 0N9
Want knowledge about
Tel. +1 613.592.5780 RapidResponse from Kinaxis-
Toll free. +1 866.236.3249 vetted experts? Join the Kinaxis
Support. +1 866.463.7877 Knowledge Network!

Email. info@[Link] [Link]