1          Smartfacts Unattended Upload Tool

1.1        Description

The Smartfacts Unattended Upload Tool allows you to publish models according to smartfacts without having to open them manually in the respective tool or upload them with a user action.

The model only has to be checked into a version management system VCS.  After check-in, this model is made available in smartfacts at periodic intervals.

1.1.1        Features of the tool

Checking out the model from the VCS

Conversion of the model to Smartfacts format

Upload of the model to Smartfacts

Currently supported tools:

• Rhapsody

• Enterprise Architect

• Innovator

• Cameo/MagicDraw with TWC

Currently supported VCS:

• Git

• Cameo/MagicDraw TWC

The tool works with provided configuration files in the form json or y(a)ml. A configuration file represents one model that is to be published after smart facts.

1.1.2        How the tool works

The following tasks are performed for each configuration.

• Checking out the model from the VCS

• Check whether any changes have occurred in the model since the last export to Smartfacts.

If changes are found, the Smartfacts Export is called for the model.

If no changes are found, the model is skipped.

• After the export file has been generated, the file is uploaded to Smartfacts. This file is then available after a short time. All users who have access to the model receive a notification within Smartfacts ("Notification") or a mail that a new model version is available.

1.2        Configuration

The following tasks are performed for each configuration.

• Checking out the model from the VCS

• Check whether any changes have occurred in the model since the last export to Smartfacts.

If changes are found, the Smartfacts Export is called for the model.

If no changes are found, the model is skipped.

• After the export file has been generated, the file is uploaded to Smartfacts. This file is then available after a short time. All users who have access to the model receive a notification within Smartfacts ("Notification") or a mail that a new model version is available.

1.2.1        Structure of the configuration file:

Each configuration file consists of the following parameters:

Source model

• GIT repository

• Branch of the model

• Credentials for retrieving the model from GIT

Target

• Smartfacts instance

• Model name under which the model is to be exported to Smartfacts

• Credentials to be allowed to publish the model according to smart facts.

1.2.1.1      JSON Format: Exemplary structure of the configuration file in JSON format

{

  "modelingTool": "RHAPSODY",

  "unitName": "MyModel",

  "doDeltaImport": false,

  "smartfactsURL": "https://developer-sfit.smartfacts.com/platform",

  "versionName": "Version.Automatically.Imported",

  "smartfactsCredentials": {

    "name": "j.nagl@mid.de",

    "password": "<MyPassword>"

  },

  "mwhId": "mwhe8588029-3b55-4b54-81e0-50ce90aa9637",

  "enabled": true,

  "gitData":{

    "url":"https://git.acme.com/HomeAlarm.git",

              "branch":"master",

              "credentials": {

                            "password": "<git password>",

                            "name": "gitea-admin"

              }

  }

}

1.2.1.2      YAML Format: Exemplary structure of the configuration file in YAML format

Same content in YAML format, which is sometimes easier to write:

---

modelingTool: RHAPSODY

unitName: MyModel

doDeltaImport: false

smartfactsURL: https://developer-sfit.smartfacts.com/platform

versionName: Version.Automatically.Imported

smartfactsCredentials:

  name: j.nagl@mid.de

  password: "<MyPassword>"

mwhId: mwhe8588029-3b55-4b54-81e0-50ce90aa9637

enabled: true

gitData:

  url: https://git.acme.com/HomeAlarm.git

  branch: master

  credentials:

    password: "<git password>"

    name: gitea-admin

1.2.2        Explanations for the individual parameters :

1.2.3        Special tags in the GIT version commentary to control the uploader

Since there is no special way in GIT to provide further information to control the uploader, the possibility was created to control the uploader by special tags in the GIT commit comment.

The following keywords are supported:

1.2.3.1.1     Name of the version:

<VersionName>This is the value for the version</ VersionName >"

Or

VersionName:This is the value for the version name.

The specified value within the XML tag or the value of the text VersionName: is taken as the value for the version description after smartfacts.

1.2.3.2      Description of the version:

<VersionDescription>This is the value for the version description

Or

VersionDescription:This is the value for the version description to the end of the line.

The specified value within the XML tag or the value of the text after Version Description: is taken as the value for the version description after smart facts.

1.2.3.3      Import priority

Each configuration is treated equally. Therefore it is usually not possible to influence which model configuration is processed first and which last.

However, if the text priority:1 is specified in a commit statement, this configuration is treated preferentially.

The default priority of a model is 5, so priorities in the range 1-9 could be specified.

If several configurations with the same priority exist, no order can be determined within these configurations and it is "random" which model in a generation run is uploaded to smart facts sooner or later.

1.2.4        Mechanism for detecting whether a new upload is necessary

1.2.4.1 GIT based models

The tool recognizes by the GIT Commit Id whether the model has been changed since the last upload. When uploading to Smartfacts, the current GIT Commit Id is stored with the model version in Smartfacts.

Before the model is converted to smart facts again or uploaded, the GIT Commit Id stored in smart facts and the Commit Id stored in the current branch are compared. If these do not differ, no upload is performed and the generation of the model is skipped.

1.2.4.2 CAMEO TWC Models

The tool queries the commit id of the specified model on TWC and checks, if the last model published to Smartfacts has a different it.

1.2.5        Directory structure

UUStarter.bat for Windows environment

UUStarter.sh for Linux environment

The batch file for starting the Uploader Tool

RhapsodyUploader.bat

Batch file that is called by the tool to start Rhapsody with the desired model and to invoke the Smartfacts Export.

Directory lib

The Java libraries required by the tool

Directory workdir: The working directory with configuration files and the "Working Directory" where the models are checked out

Content of workdir:

And therein the individual configuration files:

1.2.6        Detecting the modelwarehouse id

Log in to smartfacts and select the desired modelwarehouse

Now press F12 in the browser to open the console and debug windows.

Navigate to the web store page and select the “Local Storage”

You will now find the model warehouse id under the property “mwhid”

Copy the warehouse id to your configuration file.

1.2.7        Installing the tool

Copy the structure to e.g. C:\uploader.

1.2.7.1      Adapting batch file parameters

It is assumed that the installation was performed on drive C: and that Java version 8/241 is used. If this is not the case, the batch files must be adapted.

If you want to use another drive, you have to adapt the parameter BASEDRIVE in each batch file.

If you are not using the Java jre1.8.0_241, please adapt the parameter JAVAHOME

1.2.7.2      Adapting the tool to the Rhapsody Installation

Due to the great variance of the Rhapsody installations, another script must also be adapted.

It can be found under

<DRIVE>:uploader/tools/rhapsody/RhapsodyUploader.bat

Adjust the path of the Rhapsody installation here:

RHAPSODY_BASE_PATH

Also adjust the parameter JAVAHOME to specify the location of the java installation.

1.2.7.3      Test existing Rhapsody projects for Plugin confirmity

We provide a tool to check whether the Rhapsody projects can be processed by the Smartfacts Rhapsody Plugin.

For this purpose, all projects must be provided in a common directory. Each project must have the Smartfacts profile activated and be saved with it.

A test run can then be performed with the tool <DRIVE>:/uploader/TestRhapsody.bat. For this purpose, each model is fed to the plugin, which calls the Smartfacts converter, which creates an upload.zip for each Rhapsody model.

If an error occurs, this is logged in a log file.

The source model is not changed.

The storage point for the result and log files is located at the location

Log Files %TEMP%/smartfactsuploader/logs

Workspace files ( upload.zip )

%TEMP%/smartfactsuploader/workspaces.

Please adapt the file the corresponding parameters

PROJECTDIR : the base directory, where the Rhapsody projects are located

BASEDRIVE: The base drive

JAVAHOME: The Java Installation

1.3        Automatic schedule

We use for automatic scheduling the windows task schedule service

To do so, please follow the following instructions:

1. Call the Task scheduler in the windows menu entering “task scheduler”

1. In actions, create a new task by “Create Task….”

1. Create the task according to the following values:

General Page

Triggers Page:

Actions Page

Save it.