Introduction

This document intended to provide a detailed guide and examples on how to write EKL script to set variant effectivity on Mfg. Item.

Version – 2021x FD09 (FP2140), 2022x FD08 (FP2319), 2023x FD04 (FP2333)

Pre-requisites

Licenses – These EKL scripts call 3DSpace web services, which require specific licenses to execute as mentioned in below table. (These are referred from developer documentation of web services)

Mfg. Item related web services

•           MFN (DELMIA Manufactured Items Management)

•           CSV (Industry Innovation) For Reading Web Services

Model configuration, effectivity or IP Configuration related web services

•           CFG (Configuration Management), for all dscfg web services

•           CSV (Industry Innovation), For Reading Web Services

Disclaimer: Licenses mentioned above are as per 2021x, 2022x and 2023x documentation.

Logical Flow

The sequence of the scripts/ steps for this set effectivity EKL script is the following.

Example

Disclaimer: This code is just an example and should only be used by people who know the Enterprise Knowledge Language (EKL) and the DELMIA data model very well. The intent is not to provide a ready to deploy product code. So we are not responsible for any issues you may face with this code.

Detail Explanation

Pre-requisite

Before calling the script to set the Variant Effectivity, it is needed to 

1. Create a Model, Variants and Variant values.
2. Set/attach the configuration context on the Root or the Parent of the object, on which one want to set the Variant Effectivity. One can manually set the Configuration context or can use the EKL script available here​​​​​​​.

How to call web services

Steps followed for calling all web services.

1. Create HTTP client.
2. Define header for the HTTP client.
3. Build web service URI.
4. Perform GET/POST request.
5. Retrieve the returned response code if it is zero / as per documentation then ok else error case.
6. To retrieve the required content from the response traverse through returned data node or buffer.

For example – Below script calls web service to set effectivity of Mfg. Item instance.

In attached EKL we used hard coded effectivity expression which can be manipulated as per user requirement. Or this can be retrieved from Get effectivity script and set on selected Mfg. Item instance.

// Set Effectivity on Instance found in above step              

// Create an HTTP client
client = CreateHTTPClient()        
// Defines Headers
client.AddRequestHeaders("Content-Type: application/json")
client.AddRequestHeaders("Accept: application/json")
client.AddRequestHeaders("SecurityContext: "+securityCtx)
client.AddRequestHeaders("ENO_CSRF_TOKEN: "+csrfToken)      

let strVariantContent (String)
strVariantContent= "http://www.w3.org/2001/XMLSchema-instance\"  xmlns=\"urn:com:dassault_systemes:config\" xs:schemaLocation=\"urn:com:dassault_systemes:config CfgEffectivityExpression.xsd\">"

//Let act1 (AdvisorAction)
//act1 = `Knowledge Engineering Specification Physical00000084 A.1\Relations\Get Variant Effectivity On Mfg Item V1.0`
//act1.Run(selMfgItemOcc, strVariantContent)
if strEffectivityXprsn == "" AND strVariantContent == ""
{
          PopupMessage("Effectivity Expression not found, please send valid effectivity expression.")
                   break
}
else if strVariantContent <> "" AND strEffectivityXprsn == ""
                   strVariantContent = strVariantContent
else
                   strVariantContent = strEffectivityXprsn

Let jsonBody(String)
// Defines URI and Body
iURI = serverURL +"/resources/v1/modeler/dscfg/invoke/dscfg:setVariant"
jsonBody = "[{"
              jsonBody = jsonBody + "\"identifier\": \""+strSelctMfgItemInstPID+"\","
              jsonBody = jsonBody + "\"type\": \"dsmfg:MfgItemInstance\","
              jsonBody = jsonBody + "\"source\": \"3DSpace\","
              jsonBody = jsonBody + "\"relativePath\": \"/resources/v1/modeler/dsmfg/dsmfg:MfgItem/"+strFatherRefPid+"/dsmfg:MfgItemInstance/"+strSelctMfgItemInstPID+"\","
              jsonBody = jsonBody + "\"variantContent\": \""+ReplaceAll(strVariantContent,"\"","\\\"")+"\""

 jsonBody = jsonBody + "}]"
               
//Performs a POST request
oBuffer = client.Post(iURI, "HTTPDEFINED", jsonBody, oDTN)
// Checking if request return code is OK (rc = 0)
if (client.ReturnCode == 0)
{
                   // success
                   PopupMessage("client.ReturnCode - #, oBuffer - #", client.ReturnCode, oBuffer)
                   /*Let lEntities(List)
                   lEntities.Append(selMfgItemOcc)
                   RefreshEntities(lEntities, false)*/
}
else
{
                   // failure            
                   PopupMessage("client.ReturnCode - #, oBuffer - #", client.ReturnCode, oBuffer)
}

How to define the Input Effectivity Expression in XML format for web service

The effectivity expression, which will be used as the input for the EKL script to send to the we service needs to be given in the XML format. 

One can either use the input string argument "strEffectivityXprsn" to pass the effectivity expression or one can edit the already available Effectivity Expression, which is defined as a string variable "strVariantContent" in the script on line 175 (For single Variant and its value) or 178 (For multiple Variants and their values). 

If the "strEffectivityXprsn" is empty, then the script will  use the value stored in "strVariantContent" as a Effectivity Expression.

Below are the guidelines to edit the effectivity expression:

For single variant and its value

For effectivity expression having single variant and its value, use the following XML format

strVariantContent= "http://www.w3.org/2001/XMLSchema-instance\"  xmlns=\"urn:com:dassault_systemes:config\" xs:schemaLocation=\"urn:com:dassault_systemes:config CfgEffectivityExpression.xsd\">"

Below is the explanation of the above XML expression

The above Effectivity Expression will result into Variant Effectivity as given below:

Here, the "" tags are used to define the Model and the "" tag is used to define the Variant or Variant Value. The "" tag inside the "" tag is considered as "Variants" and the "Feature>" tag inside the " tag of "Variant" is considered as its "Variant Value".

Note: "Name" is the internal "Name" attribute of the Model, Variant or Value

Edit the Model Name, Variant Name and Variant Value Name before executing the script.

For Multiple variant and its value

For effectivity expression having multiple variants and their values, use the following XML format

strVariantContent= "http://www.w3.org/2001/XMLSchema-instance\"  xmlns=\"urn:com:dassault_systemes:config\" xs:schemaLocation=\"urn:com:dassault_systemes:config CfgEffectivityExpression.xsd\">"

Below is the explanation of the above XML expression

The above Effectivity Expression will result into Variant Effectivity as given below:

Here, the "" tags are used to define the Model and the "" tag is used to define the Variant or Variant Value. The " tag is considered as "Variants" and the "Feature>" tag inside the " tag of "Variant" is considered as its "Variant Value".

If there are multiple "Variants" used in the Effectivity Expression, then the " tags for "Variant" and "Variant" values are defined inside the "" tag as shown in the above image.

Note: "Name" is the internal "Name" attribute of the Model, Variant or Value

Edit the Model Name, Variant Names and Variant Values Name before executing the script.

Here under some Use Case about possible adaptation of the script

1. Requirement 1: Set effectivity on other type of objects in structure

In above example we saw detailed explanation of how the script is written to set the effectivity of Mfg. Item, there might be requirement where we need to set effectivity on Eng. Item, System or Resource objects. In this case, user need to modify above script and reuse them.

Below are some of the changes required in the script to use it for Eng. Item, System or Resources.

• Object selection

Based on to which type of object we want to set effectivity we will set its type.

• Use respective corpus type

In our example we used dsmfg/dsmfg:MfgItem instead of that if set effectivity is to be done on system object then use dsprcs/dsprcs:MfgProcess similar for other type of objects.

//Web Service Search Query with Parameter for Mfg Item
requestURI= serverURL + "/resources/v1/modeler/dsmfg/dsmfg:MfgItem/search?\$searchStr=" + PLMID + "&\$top=50&\$skip=0"

//Web Service Search Query with Parameter for System 
requestURI= serverURL + "/resources/v1/modeler/dsprcs/dsprcs:MfgProcess/search?\$searchStr=" + PLMID + "&\$top=50&\$skip=0"

2. Requirement 2: Set Evolution effectivity on Mfg. Item

Above example shows how to set variant effectivity on Mfg. Item, similarly if user want to set Evolution effectivity then below are some changes required in above EKL script.

• Web service URI

Modify web service URI as shown below,

 // For setVariant Effectivity Defines URI as below,
iURI = serverURL +"/resources/v1/modeler/dscfg/invoke/dscfg:setVariant"

// For setEvolution Effectivity Defines URI as below,
iURI = serverURL +"/resources/v1/modeler/dscfg/invoke/dscfg:setEvolution"

• Effectivity Expression

Modify effectivity expression as per evolution effectivity to apply, below is an example,

"http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"urn:com:dassault_systemes:config CfgEffectivityExpression.xsd\">"

• JSON Body

Build JSON request body as shown below with required identifiers and evolution expression. For more details refer Developer assistance for 2021x.

// Define Variant effectivity expression

let strVariantContent (String)
strVariantContent= "http://www.w3.org/2001/XMLSchema-instance\"  xmlns=\"urn:com:dassault_systemes:config\" xs:schemaLocation=\"urn:com:dassault_systemes:config CfgEffectivityExpression.xsd\">"

// Defines URI and Body For SetVariant Effectivity
iURI = serverURL +"/resources/v1/modeler/dscfg/invoke/dscfg:setVariant"
jsonBody = "[{"
                   jsonBody = jsonBody + "\"identifier\": \""+strSelctMfgItemInstPID+"\","
                   jsonBody = jsonBody + "\"type\": \"dsmfg:MfgItemInstance\","
                   jsonBody = jsonBody + "\"source\": \"3DSpace\","
                   jsonBody = jsonBody + "\"relativePath\": \"/resources/v1/modeler/dsmfg/dsmfg:MfgItem/"+strFatherRefPid+"/dsmfg:MfgItemInstance/"+strSelctMfgItemInstPID+"\","
                   jsonBody = jsonBody + "\"variantContent\": \""+ReplaceAll(strVariantContent,"\"","\\\"")+"\""
jsonBody = jsonBody + "}]"

// Define Evolution effectivity expression
let strEvolutionContent (String)
strEvolutionContent = "http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"urn:com:dassault_systemes:config CfgEffectivityExpression.xsd\">"

// Defines URI and Body For SetEvolution Effectivity
iURI = serverURL +"/resources/v1/modeler/dscfg/invoke/dscfg:setEvolution"
jsonBody = "[{"
                   jsonBody = jsonBody + "\"identifier\": \""+strSelctMfgItemInstPID+"\","
                   jsonBody = jsonBody + "\"type\": \"dsmfg:MfgItemInstance\","
                   jsonBody = jsonBody + "\"source\": \"3DSpace\","
                   jsonBody = jsonBody + "\"relativePath\": \"/resources/v1/modeler/dsmfg/dsmfg:MfgItem/"+strFatherRefPid+"/dsmfg:MfgItemInstance/"+strSelctMfgItemInstPID+"\","
                   jsonBody = jsonBody + "\"evolutionContent\": \""+ReplaceAll(strEvolutionContent,"\"","\\\"")+"\""

jsonBody = jsonBody + "}]"

For example – below is an example of JSON body to pass to setEvolution Effectivity web service method.

[
{
    "identifier": "F6AF82561E5700005EB271EE0003C500",
    "evolutionContent": "http://www.w3.org/2001/XMLSchema-instance\" xsi:schemaLocation=\"urn:com:dassault_systemes:config CfgEffectivityExpression.xsd\">",
    "type": "dseng:EngInstance",
    "source": "3DSpace",
    "relativePath": "/resources/v1/modeler/dseng/dseng:EngItem/F6AF82561E5700005EB123650003C100/dseng:EngInstance/F6AF82561E5700005EB271EE0003C500"
  }
]

Note – Always use internal name for all variant values, features, Model name, product state, etc...

How to Deploy

Follow below steps to deploy the above EKL script

1. Download the Provided EKL Script
2. Create one new "Physical Product" to act as container for the EKL action and give it some suitable name. For ex. "Set_Variant_Effectivity_EKL_script"
3. Create a new "Knowledge Action" in the newly created Physicals Product. Follow the sample video available on this page​​​​​​​ to know "How to create Knowledge Action".
4. Set the input arguments as explained at the top of the script in the "Input output argument" comment.
5. Edit the "strVariantContent" variable value for your model and variant. (Use variable on line 175 for single variant and use variable on line 178 for multiple variants)
6. Save the script
7. Execute the script

Author

Author-  @RR 

For any queries, please reach out to - @KA ​​​​​​​