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 :
Parameter | Description | Values |
modelingTool
| Name of the modeling tool | [RHAPSODY, ENTERPRISE_ARCHITECT,MAGICDRAW,INNOVATOR] |
unitName | Name of the unit or model as it is named in Smartfacts | Text |
smartfactsURL | Url of the Smartfacts instance, please note that /platform is appended. | URL |
versionName | The default value for the version name | Will be created by the Headless Publisher. |
smartfactsCredentials | User under whose ID the modell is to be published after Smartfacts, the user must be one model owner | |
The user name of the Smartfacts user, normally its email address, in some installations this is the user name. | ||
smartfactsCredentials.password | The password of the Smartfacts user | |
mwhId | Modelwarehouse Id ( See determination of the model warehouse Id ) | |
enabled | Default : true. The switch can be used to activate or temporarily deactivate individual configurations. | [true,false] |
gitData | GIT Connection Data | |
gitData.url | URL of Git Repositories | |
gitData.branch | Branch of the model to be used, e.g. master, release/version1 | |
gitData.credentials | Creditials for (read) access to the model | |
Name of the reading Git user | ||
gitData.credentials.password | Password of the reading Git user (if necessary) | |
eaConnectionData | EA Connection Data Section | |
eaConnectionData.modelURL | The url to the file of the ea model. | |
cameoConnectionData | CAMEO Connection Data Section | |
cameoConnectionData.twcSecure | Use Secure connection ( TWC Setup determines this flag) true,false | |
cameoConnectionData.twcURL | URL of TWC, e.g. twc.acme.com:4555 | |
cameoConnectionData.credentials | Creditials for (read) access to the model | |
Name of the reading TWC user | ||
cameoConnectionData.credentials.password | Password of the reading TWC user (if necessary) | |
cameoConnectionData.twcBranch | Name of the branch on TWC, e.g trunk | |
cameoConnectionData.modelURL | Name of the model in TWC, or the name of the CAMEO file | |
doDeltaImport | Use version delta publishing (true,false) | |
doVersionOverride | Override last recent version (true,false) |
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:
Call the Task scheduler in the windows menu entering “task scheduler”
In actions, create a new task by “Create Task….”
Create the task according to the following values:
General Page
Triggers Page:
Actions Page
Save it.