Configuring Scripts Libraries

Desigo CC scripts can be packaged together into a library. This allows those scripts to be transported with all the versioning benefits of libraries. You can also perform operations such as hashing, signing, or object association on the scripts included in a library. For background information, see Scripts Libraries.

 

Prerequisites:

  • You are authorized to handle libraries at the customization level of the scripts library.
  • System Manager is in Engineering mode.
  • System Browser is in Management View.

 

Create a Scripting Library

You can create a new scripts library in two ways: either construct the library manually or use the customization feature to automatically create the required library structure.

Method 1: Create a Customized Scripting Library

  1. In System Browser, select Project > System Settings > Libraries > L1-Headquarter > Global > Scripting.
  1. In the Library Configurator tab, click Customize the entire library to a lower level .
  • The structure of the Headquarter Scripting library is reproduced at the allowed customization level. This includes a Scripts block into which you can now import scripts.

Method 2: Manually Create a Scripting Library

  1. Select the library level where you want to create the scripting library. For example:
    Project > System Settings > Libraries > L4-Project > [folder] > […] > [scripting library]    .
  1. In the Library Configurator tab, click New and select New Library Object.
  • The library object workspace displays.
  1. In the General Settings expander, specify the following fields:
  • Discipline: Enter the name of the folder (for example, Global) under which the new library will be placed. If the folder does not exist yet it will be created.
  • System
  • (Optional) Level tag (available only for L4-Project library objects)
  • (Optional) Version
  • (Optional) Date
  • (Optional) Languages, Dependences
  1. Click Save .
  1. In the New Object dialog box, enter a name and description.
  1. Click OK.
  • The new library is added to System Browser.
  1. Select the new scripting library object.
  1. In the Library Configurator tab, click New and select New Scripts Library Block.
    NOTE: For each library you can add only one library block of this type.
  1. (Optional) Enter values into the following fields: Version, Revision, Date, Notes.
  1. Click Save .
  1. In the New Object dialog box, modify the name and description.
  1. Click OK.
  • The scripts block is added to the library. You can now import scripts into it.

 

Prepare Scripts for a Library

You want to prepare some scripts so that you can later import them into a scripts library.

  1. Write or edit the scripts using the Script Editor tab in Application View. For instructions, see Writing Scripts and Format of a Library Script.
  1. Export the scripts from the Script Editor tab to .js files or to a .zip file. For instructions, see Exporting Scripts from the Project to a File. Keep the files in a known storage location.
  • The exported .js or .zip files can then be imported into a scripting library.

 

Import Scripts into a Library

To add scripts to a library, you must import them from .js files or .zip archives. The .js and .zip files can be obtained by exporting from the Script Editor tab in Application View, or they can be produced using external editors and tools.

The scripts are hashed at the time of import to protect against subsequent modification (tampering).

  1. Select the scripts block of the library. For example: Project > System Settings > Libraries > L4-Project > […] > [scripting library] > [scripts block].
  1. Select the Script Editor tab.
  1. Click Import .
  1. In the File Open dialog box, locate and select the files (.js or .zip) containing the scripts you want to import. You can make a multiple selection.
  1. Click OK.
  1. During the import, if any script is already present in the script library, a message displays and asks what to do:
  • Click Yes to overwrite the script. In case linked objects are present, another message box displays: click Yes if you want to delete these linked objects.
  • Click No to not import the script.
  • When the import is complete, the imported scripts are added to the list in the Scripts expander. If an imported script had a comment in the first line (such as, a line starting with "//" or a text between "/*" and "*/"), this text displays in the Description column. The imported scripts are included in the project backup. They can be later exported (to a GMS file) with any other Desigo CC libraries data.
    NOTE: In the file system, the.js files of the imported scripts are stored in the corresponding libraries folder, for example, under MyProject > libraries > Global_Scripting_Project_1 > Scripts.

 

Modify a Library Script

You want to modify a script contained in a library (for example, Project > System Settings > Libraries > L4-Project > […] > [scripting library]) and update the library so that it contains the modified version of the script.

  1. If the library script is signed, unsign it before modifying it. For instructions, see Sign or Unsign Library Scripts, below.
  1. Import the script into Application View so that you can edit it. For instructions, see Importing a Library Script into the Project.
  1. Make the required changes to the script. For instructions, see Edit the Code of a Script.
  1. Export the modified script from Application View to a .js file at a known location on disk. For instructions, see Exporting Scripts from the Project to a File.
  1. Import the .js file exported in step 4 into the library. For instructions, see Import Scripts into a Library, above.
  1. If necessary, re-sign the script. For instructions, Sign or Unsign Library Scripts, below.
  1. If you kept the same file name during the import and export operations, you will be prompted to overwrite the previous version of the script: click Yes.

 

Link Objects to a Library Script

If a library script requires specific system objects to run properly, you can manually link those objects to the script, so that the system can check for the presence of the required objects. This is useful, for example, if a scripting library will be used in different projects, which may not already contain all the required objects.

  1. Select the scripts block. For example:
    Project > System Settings > Libraries > L4-Project > […] > [scripting library] > [scripts block]    .
  1. Select the Script Editor tab.
  1. Open the Scripts expander and select a script from the list.
  • The Viewer expander displays the code of the script. Here you can check for any objects referenced in the code, that you may want to link to the script.
  1. Open the Linked Objects expander.
  1. To associate a required system object to the script:
  • Drag the object from System Browser into the Linked Objects expander.
    NOTE: You cannot link objects from Event List or, in case of distributed system environment, objects that belong to a system different from the local one.
  1. To remove the link between an object and the script:
    a. Select the linked object.
    b. Click Remove.
    c. Click Yes.
  • The objects listed in the Linked Objects expander are linked to the script. The Status field indicates whether the object currently exists in the project and is of the correct type. A Create button alongside allows any missing objects to be created.

 

Create the Missing Objects Required by a Library Script

If one or multiple linked objects required by a library script are missing from the project, the following will occur:

  • When you select the library scripts block, the script displays in red (object missing) or yellow (object of incorrect type) in the list.
  • While attempting to import the library script into Application View, the following message displays: Please verify the status of linked objects of the imported file.

In this case you must check the script library and create any missing objects required to run this script properly.

  1. Select the scripts block. For example:
    Project > System Settings > Libraries > L4-Project > [..] > [scripting library] > [scripts block]    .
  1. In the Script Editor tab, open the Scripts expander.
  • The list of the scripts in this library displays. Scripts with linked objects display in green if all the objects are correct, or in yellow/red if there is a problem with the linked objects.
  1. Select the script whose missing/incorrect objects you want to repair.
  1. Open the Linked Objects expander.
  • A list of the objects linked to this script displays. The Status field indicates any objects that are missing in the current project or of the incorrect type.
  1. In System Browser, create any linked objects with status = Exists with wrong type or Not found:
    a. Click Create for the object in this state.
    b. In the dialog box, select the location where the node is to be created.
    c. Click OK.
  1. Fix any invalid links that occurred because of virtual data point type mismatch:
    a. Create the new virtual data point.
    b. Select the invalid linked object.
    c. Click Delete.
    d.     Drag the new virtual data point into the Linked Objects expander.
    e. Repeat the previous steps for any invalid links in the library.

 

Hash a Library Script

When scripts are imported into a library, they are hashed to guard against tampering. If a library script is subsequently modified directly in the file system, for example using an external editor, it will display in red when you select the scripts block. For background information, see Hash of a Library Script.

Do this procedure to check the hash values of library scripts and re-hash them if needed.

  1. Select the scripts block. For example:
    Project > System Settings > Libraries > L4-Project > […] > [scripting library] > [scripts block]    .
  1. In the Script Editor tab, open the Scripts expander.
  • Any scripts that were modified after import display in red, with the Valid Hash property set to False.
  1. Locate and select the script with the Valid Hash property set to False.
  1. Click Hash.
  • The hash value for the script is updated and the Valid Hash property is set to True.

 

Protect a Library Script

To protect intellectual property, scripts in a library can be converted to a binary format, so that the source code is not legible. For background information, see Protection of a Library Script.

  1. Select the scripts library block. For example:
    Project > System Settings > Libraries > L4-Project > […] > [scripting library] > [scripts block]    .
  1. In the Script Editor tab, open the Scripts expander.
  1. Select the script.
    NOTE: If the script has Signed set to True, click Unsign and then click Yes.
  1. Click Protect.
  • A dialog box prompts you to save a backup of the original script. This is necessary because, once a script is protected, the original source code can no longer be retrieved.
  1. Click Yes.
  • When finished, the Protected column displays True. In the Signed column, False is highlighted in red and the Signed by column displays the following text: Please sign this protected script for proper identification of the author. See Sign or Unsign Library Scripts, below.

 

Sign or Unsign Library Scripts

Scripts included in a scripts library block can be digitally signed to certify that they are authored by an authorized developer, and to protect them against subsequent modification or tampering. For background information, see Signing of a Library Script.

Install the Private Key Certificate

To be able to sign a library script you must first install the private key certificate on your local machine.

  • You received a certificate pair from a trusted certificate authority (private key file (.pfx) with a password and public key file (.cer)).
  1. Double-click the .pfx file.
  • A wizard helps you to install the certificate.
  1. In the Certificate Import Wizard page, select Local Machine.
  1. Click Next.
  1. Enter the password.
  1. Click Next.
  1. In the Certificate Store page, select Place all certificates in the following store.
  1. Click Browse and select Trusted Root Certificate store.
  1. Click OK.
  1. Click Next.
  1. Click Finish.

Sign a Library Script

  • You installed the private key certificate on your local machine.
  1. Select the scripts block. For example:
    Project > System Settings > Libraries > L4-Project > […] > [scripting library] > [scripts block]    .
  1. In the Script Editor tab, open the Scripts expander.
  1. Select the script you want to sign. It must have Signed set to False.
  1. Click Sign.
  1. In the Select Certificate dialog box, check that Store Location is User certificates.
  1. Select the Personal tab.
  1. Select the certificate previously imported and provide the certificate password, if required.
  • When the operation is completed, the Signed column displays True, while the name of the author displays in the Signed By column.

Unsign a Library Script

You can remove the signature from a previously signed library script. For example, you might want to do this if you want to modify the script.

  1. Select the scripts block. For example:
    Project > System Settings > Libraries > L4-Project > […] > [scripting library] > [scripts block]    .
  1. In the Script Editor tab, open the Scripts expander.
  1. Select the script you want to unsign. It must have Signed set to True.
  1. Click Unsign.
  1. Click Yes.

 

Delete a Script from a Scripts Library
  1. Select the scripts block. For example:
    Project > System Settings > Libraries > L4-Project > […] > [scripting library] > [scripts block]    .
  1. In the Script Editor tab, open the Scripts expander.
  1. Select the script to remove.
  1. Click Delete.
  1. Click Yes.
  • The script is removed from the Scripts expander and is no longer included in the library.
    NOTE: This will not remove the corresponding script from Application View, if you previously imported it there.