prolaborate user guides: administrator guide...the following sections will describe these steps in...

Prolaborate Guide - Administrators

Prolaborate User Guides:

AdministratorGuide

Document Version: 0.6

Date 09 Feb 2017

Author: Ian Mitchell, Prolaborate Sales & Support, [email protected]

Release Notes: This is a draft of the Prolaborate User Guide for Administrators which will eventually be delivered via the Prolaborate.com website.

This draft is for the short-term use of KPMG only, who will be informed once the production version is available.

1© Prolaborate 2017

mailto:[email protected]


Contents



Decision 1: Guide to this GuideThis guide is designed to help you use Prolaborate to give users access to your Sparx Enterprise Architect (EA) models.

It describes, for each area:

1. The decisions you need to make about how to setup Prolaborate,These sections will set out the options which Prolaborate offers, plus some advice on best practice for getting the most out of Prolaborate, based on our experience in real-world implementations.

2. Detailed instructions on how to implement your decisions in Prolaborate.This will show you in detail how to use the Administrator features of Prolaborate.

1.1 DecisionsWe’ll present these decisions in a sequence, which is just the order in which we think is most helpful.

Decision 2: - Decisions will look like this

In reality, you may be driven by, for example, the needs of a particular user group, or the needs of a specific project, so you may make the decisions in a different order.

For each decision, we’ll suggest an approach, like this:

Models and Repositories

Here you will decide which of your EA models Prolaborate users are able to see. If you have everything in one big EA model, this is easy! But even then, there are a few tricks you can use to make Prolaborateeven more useful.

Sections

Once you’ve decided which models Prolaborate can see, you need to look inside those models, and decide the granularity of access.

Users

Create users, and make those users belong to groups. Then you’re ready for…



Access Permissions

Access permissions link users/groups to Sections, and say who can do what.

Profiles and views

(this section will not be completed until later. This deals with why & how to change the Prolaborate Profiles for models and users, to deliver a more customised user experience.



Decision 3: Models and RepositoriesHere you will decide which of your EA models Prolaborate users are able to see. If you have everything in one big EA model, this is easy! But even then, there are a few tricks you can use to make Prolaborateeven more useful.

3.1 Features & Decisions

Decision 4: - Location and connectivity of EA Repository

EA users have lots of choices about where they store their EA data: local EAP files, shared EAP files or shared databases, and Prolaborate supports all those choices:

So you can connect to

an EAP file, either on the same server as Prolaborate or remote (not shown on diagram), though these don’t perform as well as databases

a database repository on the same server (option A above)

a database repository on a different server (option B)



Decision 5: – Mapping EA Repositories to Prolaborate Repositories

Prolaborate lets you map one EA repository to one or more Prolaborate Repositories. The most common way to use Prolaborate is to map them 1:1, but you can map 1: many.

Mapping 1: many can be really useful, because each Prolaborate Repository defines a ‘Profile’ (see below), which determines what parts of the EA repository can be seen, how much detailed data is displayed to users, what formats are used for lists, and lots more options.

So you might choose, for example, to let users who are just browsing the information in EA to use one Prolaborate Repository (Repository A above) and so use profile X, but have other users use Prolaborate Repository B, which uses Profile Y.

In both cases, all users are seeing the real-time content of EA Repository #1: they just get a different view of it.



5.1 Detailed Instructions

5.1.1 Adding a Prolaborate Repository

This section will illustrate how to add a Prolaborate Repository. Adding a Prolaborate repository primarily involves three steps:

1. Connect to EA Database using ODBC (in Sparx Enterprise Architect)

2. Save EA Project as EAP (Connection String)

3. Add new Prolaborate Repository using the EAP file (with connection string)

The following sections will describe these steps in detail.

5.1.1.1 Connect to EA Database using ODBC

For effective functioning of Prolaborate, the EA repository is expected to be hosted in one of the EA supported RDBMS. The first step involves the ability to be able to connect to this EA repository using Sparx EA.

Steps to connect

1. Open Enterprise Architect in the server where Prolaborate is setup.

2. Connect to the remote database using ‘Connect to Server’ option.

3. Use ODBC connection string to connect to the database server.



Ensure ‘Allow Saving Password’ or similar option is selected when creating.

5.1.1.2 Save EA Project as EAP (Connection String)

Once Sparx EA loads up the model hosted in the database repository, the project must be saved as an EAP file to save the ODBC connectivity as a connection string.

Use, Tools -> Save Shortcut As.. option in Sparx EA to save the connection string.



5.1.1.3 Add new Prolaborate Repository

Once an EAP file (connection string) is created, we are in a position to setup a Prolaborate Repository.

Steps to add a Prolaborate Repository

1. Login to Prolaborate as Admin.



2. Click on ‘Add New Repository’ button in the ‘Repositories’ screen

3. Add a New Prolaborate Repository using the EAP file that contains connection string to EA database.



Table below describes the field in the ‘Add New Repository’ form

Field Description

Repository Name Name of Prolaborate Repository

Description Short Description for Prolaborate Repository. This is what users will see when they login, so say something about what a user will find in this repository.

EAP File EAP file with connection string to connect to EA repository

Number of Users Indicative number of concurrent users to balance internal load. This option is set to control the resource usage, and doesn’t have critical impact on performance.

Enable Cache Enable Cache if Prolaborate is expected to operate over a static repository (e.g. Production repository) which is not updated at regular intervals.

The diagrams are not refreshed unless a manual reload is done if ‘Cache’ option is enabled.

Active Activate / Deactivate Prolaborate Repository

Authentication Required

If Sparx EA has ‘authentication enabled’ you must specify login / password of a EA user with total access to the model


Prolaborate Guide - Administrators5.1.2 Next Steps

Once a Prolaborate Repository is added, the next steps involve adding users to repository, adding user groups, configuring sections, configuring access permissions. These steps are described in the following sections.



Decision 6: Users and Groups, Sections and Access Permissions

These three decisions depend on one another, but we need to start somewhere, so we’ll begin with Sections, move on to Users & groups, then finish with Access permissions:

Sections split your EA model into bits: A Section defines a Package, or a diagram, or a single element in your model. It can also exclude certain packages, diagrams or elements

Users can belong to one or more groups

Access Permissions define which groups/users can see which Sections, and what permissions they have:

o Read only or Read & Write (ability to update EA directly)

o Whether they can collaborate or not. This gives them the ability to start and participate in discussions.



6.1 Example of some Section, Access Permission and user/group settings

(Don’t worry if you don’t understand this diagram right now! In the document that follows, we’ll explain it piece by piece.)

So in the example above User E is a member of group Y, which is in turn a member of group Z. So they can access:

Access Permission EA Data

Read/write

Alex M (baselined) package

Read/Write/Collaborate

Process package

Architecture – Shared PackageModelling Guides and Standards (not Requirements and Compliance package)



Read/Collaborate



Decision 7: Prolaborate ‘Sections’

7.1 Features & Decisions

A Prolaborate Section is just a single EA Package, diagram or element. Normally, it’s an EA Package.

By making some part of your EA model into a Prolaborate Section, you’re saying “this is the lowest level of access control I need”.

You could create a single Prolaborate section at the root of your EA model. You could then give people access to all of it. But this is probably not what most people want to do: most users don’t want or need to see everything.

More likely, you’ll want to split your model into ‘chunks’ or ‘sections’ which are a bit smaller. How many and how large those sections are depends on how you have structured your EA model.

This is best done using the example from above:



Decision 8: – how many sections to define, and how big

In this example, we have created sections at lots of different levels in the EA Model – Prolaborate doesn’t care where in the EA package hierarchy a package section is defined. This means that a user’s view of an EA model can be much simpler than the EA users view, and it can have a simpler structure and fewer packages.



8.1 Detailed Instructions

8.1.1 Define Sections

Once a new Prolaborate Repository is created, one can select sections to be shared. Figure below showsan EA Project browser and a corresponding sections configuration screen.

The following sections will show how to define sections in Prolaborate for a EA repository.

8.1.1.1 Drag and Drop Packages from Repository Browser

Prolaborate displays the EA model structure in Repository Browser, These packages (along with sub-packages) can be dragged and dropped into ‘Sections’ pane to add to the current Prolaborate repository.

The added items are then greyed out in the ‘Repository Browser’.



8.1.1.2 Select sub-packages to include/exclude

Prolaborate allows flexibility to choose sub-packages to be excluded from the sections, so you can retain the package structure but at the same time hide contents in the model that need not be exposed.


Prolaborate Guide - Administrators8.1.1.3 Add individual sub-packages

The previous sections indicated that you can add a package along with sub-packages. Prolaborate also allows users to drag and drop individual sub packages to sections. These can be dragged out of any hierarchy level of EA to be an item in the top level of Prolaborate Project.



Decision 9: Users and GroupsProlaborate lets you define users and groups either directly inside Prolaborate (by typing-in their email addresses one at a time) or by using information already saved in Microsoft Active Directory. Either way making good choices here will make your life easier later.

9.1 Features & decisions

Prolaborate lets you define groups of users, and allows one individual person to be a member of more than one group. Individuals and groups can then be given Access Permissions to Sections.

So the question is,

Decision 10: - How many groups to create, and which users tobe put in which groups?

The answer depends on your organisation, and who will be using Prolaborate.

This will give you maximum flexibility when it comes to the next stage – giving permissions for those users to access some sections.

10.1Detailed Instructions

10.1.1 Manage Users

Prolaborate supports flexible users and roles management and supports role based access control to contents in a Prolaborate repository. Prolaborate allows granular control to restrict levels of access (read, write, collaborate) to specific package, element, diagram and attributes.

10.1.1.1Prolaborate Users

Prolaborate supports the following types of users / User Groups. One can assign permissions to any of these user types.

User Type Description

System (Prolaborate) Users

Users added directly in Prolaborate. Login Credentials of these users are stored and maintained in Prolaborate.

Active Directory Users

Users imported from Active Directory. The login credentials of these users are stored and managed in Active Directory.



Active Directory Groups

Active Directory Groups can be imported into Prolaborate. This will enable all users belonging to an Active Directory Group to gain access to the parts of model to which the AD Group is given access too. This live sync with Active Directory greatly reduces redundant efforts in managing Users in an organization.

System (Prolaborate) User Groups

User Groups created directly in Prolaborate. Both System users and AD Users can be added to these User Groups

Collaboration Users

Another category of users are dynamically created by Prolaborate. Collaboration user is a special type of user added when a new user is invited to collaborate. These users will have access only to the content of the model specified in their collaboration invitation.

10.1.1.2Adding Users

The section below shows how to add users to Prolaborate. Add Users by clicking on ‘Add User’ button in ‘Manage Users’. Manage Users can be accessed from Settings menu or Repository Configure options, as shown in images below.



The following options are possible when adding a new User:

Add New System User

Select Users from other repositories

Add From Active Directory

By User

By Group


Prolaborate Guide - Administrators10.1.1.2.1 Add New Systems User

A System User is created and maintained in Prolaborate. Specify the required basic details and also add the new user to a user group to complete User Addition (User Groups are created by in Prolaborate)

10.1.1.2.2 Select Users from other

repositories

Prolaborate allows several repositories to be setup in the same instance. The users defined in one repository could be leveraged and added in another Prolaborate repository.

Steps

1. Select ‘Select users from other repositories’ option

2. Prolaborate displays the list of all users from other Prolaborate repositories.

3. Select the list of users to be added to the repository.

4. Click on the ‘+’ button to add those users to the current repository.



Prolaborate also identifies if a new user’s email already exists in another Prolaborate repository and notifies, and gives an option to import the user into the existing repository.

10.1.1.3Add From Active Directory

Prolaborate also allows users from Active Directory to be imported into a repository. A pre-requisite for this step would be valid Active Directory Configuration completed by Prolaborate Administrator.

In the process of adding new users, you can choose ‘Add from Active Directory’ which would then let you import Active Directory user or Active Directory group.



10.1.1.3.1 Active Directory by User

Choosing Active Directory Users import displays all active directory users. The users list is loaded fromthe pre-configured ‘LDAP Configuration’

Select the list of users to be added to the repository and click on the ‘+’ button to add those users to thecurrent repository

10.1.1.3.2 Active Directory by User Group

Choosing Active Directory Users import displays all active directory users. The users list is loaded fromthe pre-configured ‘LDAP Configuration’. Select the list of users to be added to the repository and click on the ‘+’ button to add those users to the current repository



Decision 11: Access PermissionsOnce you’ve created some Sections, and some groups of users, it’s finally time to decide who will do what.

11.1Features & Decisions

The only way that users can see, collaborate on, or edit EA data is by you giving them Access Permissions.

There are 4 options:

Read Only Users can see EA information (according to the settingsin the Profile and see all discussions, but can’t participate in discussions, or edit any data

Read and Collaborate. Users can see EA information, and can start and take part in discussions, but can’t edit EA data

Read and Write Can read and update EA information, but not take part in any discussions. Not normally used

Read, Write and Collaborate

Maximum access: users can see & edit, as well as create and participate in discussions

Decision 12: - Which level of permission to give to which users

Use the ‘write’ access permissions with great care: only give to groups of users who know what they are doing. Remember, you can control exactly which EA attributes they can change in the Profile for the Prolaborate Repository.

In general, give people access to a bit more EA information than you think they really need. But don’t give them access to everything – that will be confusing.




12.1.1 Access Permissions

Prolaborate allows the administrator to give controlled access of elements or packages to the users. This process of assigning access permissions can be done through either

SettingsAccess permissions.

ConfigureAccess permissions.

12.1.2 Types of Access Permissions:

There are four types of access permissions,



Read Gives access to view the elements of a package

Write Gives access to edit the package elements

Collaborate Gives access to participate in discussions, reviews etc.

12.1.3 Give Access permissions:

Prolaborate gives tailored access permissions to either users or user groups. Following are the steps to provide Access Permissions.

1. Select a package or element from the repository browser to which access has to be provided. Here, “Business Domain” is selected.



2. Select a user or a user group who is going to be given access.

3. Specify the type of access to be assigned.

4. If “Apply recursively “is selected, all the sub-packages, elements and diagrams within the selected package are given access


Prolaborate Guide - Administrators5. Click “Add” button.

In the above image, three groups have been assigned different types of access permissions.

12.1.4 Preview by User:

The admin user, working on assigning permissions, can view the list of elements and the assigned access permissions.



12.1.5 Assigning permissions by inviting to Collaborate

Prolaborate also allows users to quickly invite another user to collaborate on a diagram. Using ‘Invite Collaborators’ option in Share button

Image above shows that Beth is invited using ‘Invite Collaborators’ option for a diagram that she isn’t assigned any access permission.


Prolaborate Guide - AdministratorsOne of the two outcomes would happen as a result

12.1.6 Automatically added permission

If the invited user (in the above scenario, Beth) is a user in the Repository, but the user doesn’t have the permissions to read and collaborate on the diagram, Prolaborate will automatically add Read, collaborate rights to the user.

12.1.7 Non-Existing user – added as Collaboration User

If the user invited for collaboration is not an existing user, then the user gets added as a ‘Collaboration user’ and their access is confined to the diagrams he or she was invited to collaborate on. Image below shows a new (non Prolaborate user) Nick is invited to collaborate on a diagram.



As a result of the above step Nick will be added as a ‘Collaboration User’ and will be shown in ‘Invited Users for Collaboration’



Decision 13: Profiles and views(This section currently incomplete)

13.1Features & Decisions

13.1.1 Prolaborate Profiles

Each Prolaborate Repository has a Profile, which can be edited by the super-administrator and administrators for the repository.

Prolaborate provides you with Profiles for basic UML function (such as requirements, use cases, classes etc) as well as two of the most popular UML extensions: BPMN and Archimate.

If you have created or bought other MDGs1, then Prolaborate can make use of those as well.

Prolaborate allows you to import MDGs, and makes them into Prolaborate Profiles, which let you extended them even more, to hide some element types or attributes, and make other attributes editable.

For Example, A BPMN Activity in the BPMN MDG contains a large number of EA Tagged Values associated with it - up to 20! However only a handful will be useful for most people. In EA, it’s hard tohide the un-used ones from users: they just add to the clutter. With Prolaborate, you can easily hide these un-used bits of EA MDGs from users, make some of them read-only, other read-write, and even hide whole element types if required.

And you can do this for the built-in UML Profiles as well.

The aim of all of this is to (1) re-use your existing investment in UML and MDGs and (2) give your Prolaborate users the simplest, most efficient view of your EA information.

The following sections will illustrate how to extend a Sparx EA MDG to create simplified views in Prolaborate.

1 You may already know that you can extend Sparx EA by creating ‘MDGs’. An MDG is a way of creating new types of element, new attributes on those elements, and even new kinds of diagram and toolbox. These are so powerful that lots of EA features are delivered – by Sparx themselves – using MDGs, for example, the built-in MDGs for BPMN Process Modelling and Archimate Enterprise Architecture modelling.


Prolaborate Guide - AdministratorsThe Prolaborate Profile is used together with the Access Permissions to decide who can see and updatewhat information. If a user has Read-only (not update) permissions to a part of the model, even if the Profile being used says some attributes are potentially editable, that user still won’t be able to edit those attributes: the Access Permissions override the Profile.

Only if the access permissions say they have edit rights AND the Profile says an attribute is read/write will a user being able to do edits.

The instructions below show you how to see what kinds of elements and diagrams are in a profile, and how to set the visibility and editability of individual attributes.

13.1.2 Customising the Prolaborate User Interface

The Profile – based on its MDG – defines which attributes are visible to suitable authorised users. As itdoes that, it changes the appearance of the Prolaborate user interface, so that hidden attributes just don’t appear.

You can edit attributes via the ‘Attributes’ page:


Prolaborate Guide - AdministratorsThe attributes page is where your users can view, and potentially update EA data.

The order of the attributes, and which ones are visible and editable is controlled by the Profile for the Repository, specifically the part of the profile which defines how Use Cases appear.

The ‘Use Case’ Profile used in this example looks like this:

We have made the name and author attributes read-only, but the Notes attribute can be editable by authorised users.

We also added a new attribute – not in the MDG – called ‘External Ref’, made it editable, and also added some help or it.

13.1.3 Lists of Elements

The same Profile is also used to customise the Use Case when it appears in a list:

Note: the ‘notes’ attribute is currently not shown in these lists, since it may be very large and contain complex data.



Decision 1: Decide which MDGs to use, and which elements and attributes are visible/editable by users


13.2.1 Prolaborate Profile

A Prolaborate profile allows users to extend Sparx EA MDG and create a customized profile for better user experience. A Prolaborate profile is a collection of the following

List of visible stereotypes in Project Browser

List of pre=defined attributes (default properties and technology tagged values), visible for stereotypes

Custom attributes (tagged values) associated with stereotypes

Custom form definitions for stereotypes

13.2.1.1List of Visible stereotypes in Project browser

Sparx EA project browser lists a comprehensive list of all items in a diagram, which includes less significant items such as decision nodes, start events end events, etc. Prolaborate allows modellers to control what is shown in the Repository browser, Click on the eye icon to control visibility.



13.2.1.2List of Pre-defined attributes visible for stereotypes

The list of pre-defined attributes visible for a stereotype includes the default attributes from Sparx EA and the list of tagged values associated to a particular stereotype (as per the supported technology). The user can include only a selected set of attributes amongst the pre-defined ones. This flexibility to exclude less important attributes from stakeholders view is a great way to reduce complexity from stakeholders and improves attention.

13.2.1.3Custom Attributes associated with stereotypes

Prolaborate allows users to define custom attributes to be associated to any stereotype definition from the MDG. This is equivalent to extending the MDG technology with new tagged values in Sparx EA. These custom attributes could be one of the supported tagged value types in Sparx EA and could be added using the simplified User Interface in Prolaborate.



1.1.1.1 Custom form definitions for stereotypes

Prolaborate allows users to configure custom forms for each stereotype in the MDG technology. For example, Author could have a set of attributes grouped collated in a form for the BPMN Activity and another forum for BPMN Business Process, and so on.

Figure below shows how a form is designed for BPMN Activity, this form contains three groups, the default attributes (or the EA properties), some selected attributes from BPMN Technology and some new attributes custom defined in Prolaborate. Please note however there is no restriction on using any type of attributes in any group.



13.2.2 Selecting Default Profile

Prolaborate allows multiple profiles to be defined for any stereotype, it gives author the flexibility to set any of these profiles as default at any point of time. The profile set as default will be shown to all users of the repository.



Decision 14: Other(for next version)

14.1Features & decisions



prolaborate user guides: administrator guide...the following sections will describe these steps in...

Documents