BackStage Projects

This is a collection of articles relating to the Projects feature in BackStage. You can find out how to create projects and environments, and how to get started with the Deployment Planner to create deployment diagrams.


BackStage Projects: Introduction

This article gives some background about the Projects feature in BackStage.

Projects

Projects is a means to obtain information about how the ForgeRock Identity Platform is being used. This includes gathering metadata, such as deployment structures/diagrams, as well as log or configuration files, or calendar events relating to a deployment project. This information helps us understand more about your projects and the way you use our products, so that we can give you quicker and more accurate responses via Support. It also helps us speed up the on-boarding process by replacing a long list of questions we would otherwise have to ask.

If you have an active subscription, BackStage allows you to create projects for your subscription; each project being a collection of environments and calendar events. Environments contain deployment information, that is, your deployment topology, including details about how ForgeRock products are being used, what features are enabled, etc. Once you have a deployment diagram in BackStage, you can reference it when opening a ticket, providing our support team with some context right away, which means you can save the time by not having to collect and send your environment details each time you open a support ticket.

Customers can also share any important events or deadlines with us to alert our support team in time to make sure they are prepared to render any special assistance if required during a go-live event or similar planned situation.

Note

If you are not a ForgeRock customer, you can still create private projects and use the Deployment Planner in BackStage.

You can read more about this in the following articles:

Data Security

We take data security and access management very seriously. Our access control policies ensure that your Projects data can only be accessed by authorized members of the subscription the data belongs to, and only people at ForgeRock with the privilege to access customer information. Your deployment details and files will not be shared with any third-parties.


Working with Projects in BackStage

This article explains how to set up and manage projects for your subscriptions.

Projects

BackStage allows users to share information about their ForgeRock implementation projects with ForgeRock.

Registered users can have private projects, and customers can also create projects that belong to their subscription (and is shared with all members of that subscription).

Projects can have environments (see Working with Environments in BackStage). 

Subscription projects can have a list of calendar events (such as go-live dates and other deadlines).

Customers can also upload and attach files for their projects.

All members of a subscription (as well as ForgeRock support) can access and make changes to all projects and environments of a subscription.

Creating Projects

Note

To create a project, you need to register an account and log in to BackStage.

Go to the Projects page.

The Projects page shows a list of your private projects and your subscriptions. For each subscription, you can have one or more project.

  • To create a private project, click the "New Project" button under "Private Projects".
  • To create a new project for a subscription, click the "New Project" button below the organization's name. Fill out the name and the optional description field, then click "Create". Your project will be added to the list.
Caution

If you have multiple subscriptions, make sure to create the project for the correct one. Projects and environments are visible and editable by all members of the subscription they belong to.

To see the details of your new project, click on it. The project details page lets you change the name and description, archive or restore the project, or add calendar events and environments.

Archiving and Restoring Projects

Projects cannot be completely deleted, but they can be archived. Archived projects do not get analyzed and are hidden by default. Archiving a project will also archive all of its environments and calendar events.

To archive a project, click the red "Archive" button in the top right corner of the Project Details page and accept the confirmation popup.

Archived projects can be listed on the projects page. 

Archived projects can be restored at any time by clicking "Restore" on the Project Details page.

Project Calendar Events

By creating calendar events for a subscription project, you can inform/alert ForgeRock Support about an upcoming event in your project's lifecycle (such as a go-live or an upgrade event). Calendar events will automatically alert the support team in advance so they can prepare and make sure to provide any special assistance you may require.

To create a calendar event, scroll to the Calendar section of the Project Details page, and click "Add Event".

Fill out the start and end dates, the description and the event type. If all fields are filled out, the event gets created right away.

Once the event has been created, you have the option to mark it as done or delete it. You can change the properties of an event after it has been created.

Note

The project calendar is only available for non-private projects (i.e. projects that belong to a subscription).

Environments In a Project

See Working with Environments in BackStage on how to manage your environments.


Uploading Files

This article explains how to upload files in BackStage.

File Uploads

Customers with an active subscription have the option to upload files for their support tickets and deployment projects (see Working with Projects in BackStage).

Files uploaded for a ticket or project will be writable by all subscription admins and readable by all subscription members.

File metadata (description, tags, permissions) can be edited after a file has been uploaded by any user with write permissions to the file. The file's content can be updated (i.e. a new file can be uploaded in its place), and it can also be deleted.

When a file's content is updated, the old versions are kept. When a file is deleted, all versions of its content are removed from the storage service, but the file's metadata is kept (and becomes hidden by default).

Note

We don't impose a size limit, but we clean up unused large files regularly.

Note

The uploader in the BackStage UI uses HTML5, which is not supported by Internet Explorer 9.

Uploading Files for Tickets

Files can be uploaded for support tickets on the New Ticket page when the ticket is opened, as well as on the Tickets page, after the ticket was opened.

ticket file uploads

When uploading files for a ticket, you may choose to link the lifecycle of the files to that of the ticket. This means that these files will be automatically deleted when the ticket's status changes to "closed" (14 days after it has been submitted as "solved"). Since a file can be attached to more than one ticket, the file is only deleted when the all related tickets are closed.

To link the lifecycle of the attachment to the ticket, select the "Automatically delete attached files when the ticket is closed (only applies to new attachments)" checkbox under the file uploader:

Note

Note that the default behavior is to keep files permanently (that is, not link their lifecycles to the ticket).

Storage Service

The storage system for project files is based on Amazon's S3 service. Files uploaded for projects are stored in S3 buckets (the bucket can be selected from a dropdown).

When a file is uploaded, its metadata is stored in BackStage and the file is transferred directly to Amazon's S3 API.

All file transfers use SSL for encrypting the payload, and all files are also encrypted on the server with a random key.

Files can only be accessed with a signature (which is provided by BackStage). In order to get a signature for a file, the user must have an active session and have permissions to access the file. These permissions can be configured by the owner of the file (the admins of the subscription and the user who uploaded the file, as long as they are a member of the subscription).

The uploader in the BackStage UI performs a chunked (multipart) upload for all files and sends them directly to the storage service. The upload and download speed may depend on your location and the storage bucket you selected.

Caution

ForgeRock has a global service, which means that these files may be accessed in any country where ForgeRock operates. By uploading a file to BackStage, you guarantee that the file does not contain any information that has any limitations as to where it can be accessed geographically.

Editing the File Metadata

Once a file is uploaded, you can edit its metadata in the details dialog box. If you have write access to a file, you can change the description, the tags and the permissions of the file.

file options

file details


Working with Environments in BackStage

This article explains how to create and manage environments in your BackStage projects.

Environments

Environments in BackStage are entities that describe a ForgeRock deployment. An environment has a name, description and a lifecycle, and it can contain a deployment structure.

Environments always belong to a project (see Working with Projects in BackStage).

A deployment structure is a collection of machines, software and connections. This structure may contain all the necessary information to describe how you're using each product in the ForgeRock Identity Platform. Such information is vital for ForgeRock Support in assisting with your issues. By providing an accurate description of your deployment, you will receive quicker and more accurate responses from our team, since they will already know where to look for a root cause, rather than having to collect general data about your system each time.

Deployment structures are visualized as diagrams, and can be edited with a graphical editor tool.

Creating and Updating Environments

To create an environment, go to one of your projects and scroll to the Environments section of the Project Details page.

Click "Add Project" and fill out the form. Name and Lifecycle are required fields.

When you click "Create", the environment will be added to the list. You can edit the environment's name, description and lifecycle on the Environment Details page by clicking on the environment on the list.

Environments can be archived and restored, just like Projects. Archived Environments don't get analyzed and are hidden by default.

To archive an environment, click "Archive" on the Environment Details page.

You can restore an archived environment by clicking "Restore" in the top right corner of the Environment Details page.

Revisions

Environments are versioned. This means that every time you save an environment, you create a new revision of it. All previous revisions are kept, and you can always go back and open any revision. Editing and then saving the environment will create a new revision, which will become the newest one. If you made a mistake, you can go back to the previous revision and save again, thus making the incorrect revision obsolete.

Caution

Because each save creates a new revision, if several users work on the same revision and save it, they will all get new revisions, but only one of them will be the "newest". Merging the different revisions can only be done manually.

Summary

The Environment Details page has a Summary section where you can see an overview of your deployment. The summary engine in BackStage analyzes the deployment structure and extracts information about certain key aspects, such as the number of OpenAM instances or the different OpenDJ versions in use.

Deployment Planner

You can access the Deployment Planner from the Environment Details page. The Deployment Planner is an application within BackStage that lets you graphically edit your deployment structures by drawing deployment diagrams.

See also: Working with the Deployment Planner in BackStage

Referencing Environments in Support Tickets

If you have a valid subscription, you can add a reference to an environment when creating a new support ticket. There is a new section in the ticket form called Environment. It has a list of all the projects for the selected subscription; once you select a project, you can click on one of the environments in that projects to add it to the ticket. Our support team will see the reference to that environment and they will be able to look it up in BackStage to get some context about your deployment.


Working with the Deployment Planner in BackStage

This article describes how to use the Deployment Planner to create and edit deployment structures.

The Deployment Planner

The Deployment Planner is an application built into BackStage that lets you visualize and edit the deployment structure of an environment (see Working with Environments in BackStage). The deployment structure is rendered as a diagram which can be edited in the browser.

Deployment structures consist of machine groups, machines, software and connections. Various rules apply as to how these components can relate to each other to ensure the integrity of the diagram and the underlying data structure (see below).

The Deployment Planner UI has 3 main parts:

  • Components: these are stencils that you can drag and drop to the drawing board
  • Topology: the main drawing board; a visualization of your deployment structure
  • Properties: each component in the structure has its own set of parameters that you can customize (such as name, description, etc.)

To add a component to the diagram, drag a stencil from the list of components to the drawing board, then select it by clicking on it, and edit its properties on the right.

You can save the environment on this page (which will create a new revision), or undo any changes you have made since the last save by clicking "Revert". 

Components and Rules

  • Machine Groups
    • May contain machines 
    • Cannot be connected or bound
    • Can be cloned
  • Machines
    • May be embedded in machine groups
    • May contain software
    • Cannot be connected or bound
    • Can be cloned
  • Software
    • Must be embedded in a machine or another software component
    • May contain other software
    • May be connected to another software component
    • May be bound to another software component of the same type
    • Can be cloned
  • Connections
    • Can only exist between two pieces of software

Component Tools and Properties

Each component can be selected by a single click. Selecting a machine group, machine or software will show the Component Toolbar.

The toolbar lets you perform the following actions:

  • Delete component
  • Clone component
  • Create connection (software only)
  • Create binding (software only)

Selecting a component also lets you edit its settings in the Properties panel on the right.

Some properties are nested – click the + icon to expand all the available options within a category (such as "SAML" for OpenAM).

Some properties are required – the diagram will show any components with missing required properties in red to highlight any incomplete or invalid components.

Connections

You can create connections between two pieces of software to show that some form of communication takes place between them (such as an LDAP connection between an OpenAM and an OpenDJ instance). Connections have their own properties (such as protocol, SSL/plain,  classifier).

Connections are automatically routed, so they might overlap. You can change their path by adding vertices if you double click on the connection's path.

You can have multiple connections between the same two software instances.

Note

Certain kinds of software don't allow all kinds of connections.

Bindings

Binding means the binding of properties across multiple pieces of software.

Different instances of the same type of software (e.g. OpenAM) can be bound together into a swarm. The binding between these instances will ensure that their properties are always synchronized (i.e. you only have to change a property on one instance, and the other instances in the swarm will automatically get updated).

The number of software instances in a binding swarm is not limited.

When you create a binding from software A to software B, you are adding A to B's swarm, effectively replacing the properties of A with those of B.

You can unbind a software instance by creating an invalid binding for it (click and drag the bind icon, then drop on something unbindable).

Export and Import

Deployment structures can be exported and imported in the Deployment Planner. This feature allows you to share your deployment diagrams with other projects. Structures are exported as a JSON file.

To export a deployment, click the Export button in the Deployment planner. The JSON file will be downloaded as an attachment.

To import a deployment structure, click the Import button in the Deployment Planner and choose an exported deployment JSON file in the dialog. The deployment will be loaded on the worksheet. Don't forget to save your deployment diagram if you wish to keep the imported changes.

Note

This feature is only supported by modern browsers (IE10+)


Copyright and TrademarksCopyright © 2018 ForgeRock, all rights reserved.

This content has been optimized for printing.

Loading...