Prolaborate User Guides: Administrator Guide Document Version: 0.6 Date 09 Feb 2017 Author: Ian Mitchell, Prolaborate Sales & Support, ian@prolaborate.com 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
2
Contents 3
Decision 1: Guide to this Guide This 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 Decisions We 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 Prolaborate even 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 4
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. 5
Decision 3: 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 Prolaborate even 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) 6
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. 7
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. 8
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. 9
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. 10
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. 11
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 12
5.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. 13
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. 14
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 Alex M (baselined) package Read/write Process package Read/W rite/collaborate Architecture Shared Package Modelling Guides and Standards (not Requirements and Compliance package) 15
Read/Collaborate 16
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: 17
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. 18
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 shows an 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 subpackages) 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. 19
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. 20
8.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. 21
Decision 9: Users and Groups Prolaborate 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 to be 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. 22
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. 23
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 24
10.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. 25
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. 26
10.1.1.3.1 Active Directory by User Choosing Active Directory Users import displays all active directory users. The users list is loaded from the 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 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 from the 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 27
28
Decision 11: Access Permissions Once 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 settings in 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. 29
12.1Detailed Instructions 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 Settings Access permissions. Configure Access permissions. 12.1.2 Types of Access Permissions: There are four types of access permissions, 30
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. 31
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 32
5. 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. 33
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. 34
One 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. 35
As a result of the above step Nick will be added as a Collaboration User and will be shown in Invited Users for Collaboration 36
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 to hide 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. 37
The Prolaborate Profile is used together with the Access Permissions to decide who can see and update what 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 it does 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: 38
The 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. 39
Decision 1: Decide which MDGs to use, and which elements and attributes are visible/editable by users 13.2Detailed Instructions 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. 40
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. 41
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. 42
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. 43
44
Decision 14: Other (for next version) 14.1Features & decisions 14.2Detailed Instructions 45