Skip to content
This repository has been archived by the owner on Sep 20, 2024. It is now read-only.

Documentation: Few updates #3698

Merged
merged 9 commits into from
Aug 23, 2022
Merged

Documentation: Few updates #3698

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
2ea2779
update ftrack cli commands
iLLiCiTiT Aug 19, 2022
752f1cd
removed outdated repositories information
iLLiCiTiT Aug 19, 2022
40efddb
removed eventserver from global cli commands
iLLiCiTiT Aug 19, 2022
ce4c00d
add information about naming limitations to key concepts
iLLiCiTiT Aug 19, 2022
2591c1f
add link to key concepts into system introduction
iLLiCiTiT Aug 19, 2022
3176a01
replaced changelog and upgrade notes with releases information
iLLiCiTiT Aug 23, 2022
7466063
Fix typo
iLLiCiTiT Aug 23, 2022
bf5584d
Change avalon to openpype
iLLiCiTiT Aug 23, 2022
4943b78
grammar fix
iLLiCiTiT Aug 23, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 0 additions & 19 deletions website/docs/admin_openpype_commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,6 @@ For more information [see here](admin_use.md#run-openpype).
| module | Run command line arguments for modules. | |
| repack-version | Tool to re-create version zip. | [📑](#repack-version-arguments) |
| tray | Launch OpenPype Tray. | [📑](#tray-arguments)
| eventserver | This should be ideally used by system service (such as systemd or upstart on linux and window service). | [📑](#eventserver-arguments) |
| launch | Launch application in Pype environment. | [📑](#launch-arguments) |
| publish | Pype takes JSON from provided path and use it to publish data in it. | [📑](#publish-arguments) |
| extractenvironments | Extract environment variables for entered context to a json file. | [📑](#extractenvironments-arguments) |
Expand All @@ -57,25 +56,7 @@ For more information [see here](admin_use.md#run-openpype).
openpype_console tray
```
---
### `launch` arguments {#eventserver-arguments}
You have to set either proper environment variables to provide URL and credentials or use
option to specify them.

| Argument | Description |
| --- | --- |
| `--ftrack-url` | URL to ftrack server (can be set with `FTRACK_SERVER`) |
| `--ftrack-user` |user name to log in to ftrack (can be set with `FTRACK_API_USER`) |
| `--ftrack-api-key` | ftrack api key (can be set with `FTRACK_API_KEY`) |
| `--legacy` | run event server without mongo storing |
| `--clockify-api-key` | Clockify API key (can be set with `CLOCKIFY_API_KEY`) |
| `--clockify-workspace` | Clockify workspace (can be set with `CLOCKIFY_WORKSPACE`) |

To run ftrack event server:
```shell
openpype_console eventserver --ftrack-url=<url> --ftrack-user=<user> --ftrack-api-key=<key>
```

---
### `launch` arguments {#launch-arguments}

| Argument | Description |
Expand Down
7 changes: 7 additions & 0 deletions website/docs/artist_concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ sidebar_label: Key Concepts

In our pipeline all the main entities the project is made from are internally considered *'Assets'*. Episode, sequence, shot, character, prop, etc. All of these behave identically in the pipeline. Asset names need to be absolutely unique within the project because they are their key identifier.

OpenPype has limitation regarging duplicated names. Name of assets must be unique across whole project.
iLLiCiTiT marked this conversation as resolved.
Show resolved Hide resolved

### Subset

Usually, an asset needs to be created in multiple *'flavours'*. A character might have multiple different looks, model needs to be published in different resolutions, a standard animation rig might not be usable in a crowd system and so on. 'Subsets' are here to accommodate all this variety that might be needed within a single asset. A model might have subset: *'main'*, *'proxy'*, *'sculpt'*, while data of *'look'* family could have subsets *'main'*, *'dirty'*, *'damaged'*. Subsets have some recommendations for their names, but ultimately it's up to the artist to use them for separation of publishes when needed.
Expand All @@ -24,6 +26,11 @@ A numbered iteration of a given subset. Each version contains at least one [repr

Each published variant can come out of the software in multiple representations. All of them hold exactly the same data, but in different formats. A model, for example, might be saved as `.OBJ`, Alembic, Maya geometry or as all of them, to be ready for pickup in any other applications supporting these formats.


#### Naming convention

At this moment names of assets, tasks, subsets or representations can contain only letters, numbers and underscore.
BigRoy marked this conversation as resolved.
Show resolved Hide resolved

### Family

Each published [subset][3b89d8e0] can have exactly one family assigned to it. Family determines the type of data that the subset holds. Family doesn't dictate the file type, but can enforce certain technical specifications. For example OpenPype default configuration expects `model` family to only contain geometry without any shaders or joints when it is published.
Expand Down
28 changes: 13 additions & 15 deletions website/docs/module_ftrack.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Ftrack is currently the main project management option for OpenPype. This docume
## Prepare Ftrack for OpenPype

### Server URL
If you want to connect Ftrack to OpenPype you might need to make few changes in Ftrack settings. These changes would take a long time to do manually, so we prepared a few Ftrack actions to help you out. First, you'll need to launch OpenPype settings, enable [Ftrack module](admin_settings_system.md#Ftrack), and enter the address to your Ftrack server.
If you want to connect Ftrack to OpenPype you might need to make few changes in Ftrack settings. These changes would take a long time to do manually, so we prepared a few Ftrack actions to help you out. First, you'll need to launch OpenPype settings, enable [Ftrack module](admin_settings_system.md#Ftrack), and enter the address to your Ftrack server.

### Login
Once your server is configured, restart OpenPype and you should be prompted to enter your [Ftrack credentials](artist_ftrack.md#How-to-use-Ftrack-in-OpenPype) to be able to run our Ftrack actions. If you are already logged in to Ftrack in your browser, it is enough to press `Ftrack login` and it will connect automatically.
Expand All @@ -26,15 +26,15 @@ You can only use our Ftrack Actions and publish to Ftrack if each artist is logg
### Custom Attributes
After successfully connecting OpenPype with you Ftrack, you can right click on any project in Ftrack and you should see a bunch of actions available. The most important one is called `OpenPype Admin` and contains multiple options inside.

To prepare Ftrack for working with OpenPype you'll need to run [OpenPype Admin - Create/Update Custom Attributes](manager_ftrack_actions.md#create-update-avalon-attributes), which creates and sets the Custom Attributes necessary for OpenPype to function.
To prepare Ftrack for working with OpenPype you'll need to run [OpenPype Admin - Create/Update Custom Attributes](manager_ftrack_actions.md#create-update-avalon-attributes), which creates and sets the Custom Attributes necessary for OpenPype to function.



## Event Server
Ftrack Event Server is the key to automation of many tasks like _status change_, _thumbnail update_, _automatic synchronization to Avalon database_ and many more. Event server should run at all times to perform the required processing as it is not possible to catch some of them retrospectively with enough certainty.

### Running event server
There are specific launch arguments for event server. With `openpype_console eventserver` you can launch event server but without prior preparation it will terminate immediately. The reason is that event server requires 3 pieces of information: _Ftrack server url_, _paths to events_ and _credentials (Username and API key)_. Ftrack server URL and Event path are set from OpenPype's environments by default, but the credentials must be done separatelly for security reasons.
There are specific launch arguments for event server. With `openpype_console module ftrack eventserver` you can launch event server but without prior preparation it will terminate immediately. The reason is that event server requires 3 pieces of information: _Ftrack server url_, _paths to events_ and _credentials (Username and API key)_. Ftrack server URL and Event path are set from OpenPype's environments by default, but the credentials must be done separatelly for security reasons.



Expand All @@ -53,7 +53,7 @@ There are specific launch arguments for event server. With `openpype_console eve
- **`--ftrack-api-key "00000aaa-11bb-22cc-33dd-444444eeeee"`** : User's API key
- `--ftrack-url "https://yourdomain.ftrackapp.com/"` : Ftrack server URL _(it is not needed to enter if you have set `FTRACK_SERVER` in OpenPype' environments)_

So if you want to use OpenPype's environments then you can launch event server for first time with these arguments `openpype_console.exe eventserver --ftrack-user "my.username" --ftrack-api-key "00000aaa-11bb-22cc-33dd-444444eeeee" --store-credentials`. Since that time, if everything was entered correctly, you can launch event server with `openpype_console.exe eventserver`.
So if you want to use OpenPype's environments then you can launch event server for first time with these arguments `openpype_console.exe module ftrack eventserver --ftrack-user "my.username" --ftrack-api-key "00000aaa-11bb-22cc-33dd-444444eeeee" --store-credentials`. Since that time, if everything was entered correctly, you can launch event server with `openpype_console.exe module ftrack eventserver`.

</TabItem>
<TabItem value="env">
Expand All @@ -72,7 +72,7 @@ We do not recommend setting your Ftrack user and api key environments in a persi

### Where to run event server

We recommend you to run event server on stable server machine with ability to connect to Avalon database and Ftrack web server. Best practice we recommend is to run event server as service. It can be Windows or Linux.
We recommend you to run event server on stable server machine with ability to connect to Avalon database and Ftrack web server. Best practice we recommend is to run event server as service. It can be Windows or Linux.
iLLiCiTiT marked this conversation as resolved.
Show resolved Hide resolved

:::important
Event server should **not** run more than once! It may cause major issues.
Expand All @@ -99,11 +99,10 @@ Event server should **not** run more than once! It may cause major issues.
- add content to the file:
```sh
#!/usr/bin/env bash
export OPENPYPE_DEBUG=1
export OPENPYPE_MONGO=<openpype-mongo-url>

pushd /mnt/path/to/openpype
./openpype_console eventserver --ftrack-user <openpype-admin-user> --ftrack-api-key <api-key>
./openpype_console module ftrack eventserver --ftrack-user <openpype-admin-user> --ftrack-api-key <api-key> --debug
```
- change file permission:
`sudo chmod 0755 /opt/openpype/run_event_server.sh`
Expand Down Expand Up @@ -140,14 +139,13 @@ WantedBy=multi-user.target
<TabItem value="win">

- create service file: `openpype-ftrack-eventserver.bat`
- add content to the service file:
- add content to the service file:
```sh
@echo off
set OPENPYPE_DEBUG=1
set OPENPYPE_MONGO=<openpype-mongo-url>

pushd \\path\to\openpype
openpype_console.exe eventserver --ftrack-user <openpype-admin-user> --ftrack-api-key <api-key>
openpype_console.exe module ftrack eventserver --ftrack-user <openpype-admin-user> --ftrack-api-key <api-key> --debug
```
- download and install `nssm.cc`
- create Windows service according to nssm.cc manual
Expand All @@ -174,7 +172,7 @@ This event updates entities on their changes Ftrack. When new entity is created
Deleting an entity by Ftrack's default is not processed for security reasons _(to delete entity use [Delete Asset/Subset action](manager_ftrack_actions.md#delete-asset-subset))_.
:::

### Synchronize Hierarchical and Entity Attributes
### Synchronize Hierarchical and Entity Attributes

Auto-synchronization of hierarchical attributes from Ftrack entities.

Expand All @@ -190,7 +188,7 @@ Change status of next task from `Not started` to `Ready` when previous task is a

Multiple detailed rules for next task update can be configured in the settings.

### Delete Avalon ID from new entity
### Delete Avalon ID from new entity

Is used to remove value from `Avalon/Mongo Id` Custom Attribute when entity is created.

Expand All @@ -215,7 +213,7 @@ This event handler allows setting of different status to a first created Asset V
This is useful for example if first version publish doesn't contain any actual reviewable work, but is only used for roundtrip conform check, in which case this version could receive status `pending conform` instead of standard `pending review`

### Update status on next task
Change status on next task by task types order when task status state changed to "Done". All tasks with the same Task mapping of next task status changes From → To. Some status can be ignored.
Change status on next task by task types order when task status state changed to "Done". All tasks with the same Task mapping of next task status changes From → To. Some status can be ignored.

## Publish plugins

Expand All @@ -238,7 +236,7 @@ Add Ftrack Family: enabled

#### Advanced adding if additional families present

In special cases adding 'ftrack' based on main family ('Families' set higher) is not enough.
In special cases adding 'ftrack' based on main family ('Families' set higher) is not enough.
(For example upload to Ftrack for 'plate' main family should only happen if 'review' is contained in instance 'families', not added in other cases. )

![Collect Ftrack Family](assets/ftrack/ftrack-collect-advanced.png)
![Collect Ftrack Family](assets/ftrack/ftrack-collect-advanced.png)
23 changes: 1 addition & 22 deletions website/docs/system_introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ various usage scenarios.

You can find detailed breakdown of technical requirements [here](dev_requirements), but in general OpenPype should be able
to operate in most studios fairly quickly. The main obstacles are usually related to workflows and habits, that
might now be fully compatible with what OpenPype is expecting or enforcing.
might now be fully compatible with what OpenPype is expecting or enforcing. It is recommended to go through artists [key concepts](artist_concepts) to get idea about basics.
iLLiCiTiT marked this conversation as resolved.
Show resolved Hide resolved

Keep in mind that if you run into any workflows that are not supported, it's usually just because we haven't hit
that particular case and it can most likely be added upon request.
Expand Down Expand Up @@ -48,24 +48,3 @@ to the table
- Some DCCs do not support using Environment variables in file paths. This will make it very hard to maintain full multiplatform
compatibility as well variable storage roots.
- Relying on VPN connection and using it to work directly of network storage will be painfully slow.


## Repositories

### [OpenPype](https://github.com/pypeclub/pype)

This is where vast majority of the code that works with your data lives. It acts
as Avalon-Config, if we're speaking in avalon terms.

Avalon gives us the ability to work with a certain host, say Maya, in a standardized manner, but OpenPype defines **how** we work with all the data, allows most of the behavior to be configured on a very granular level and provides a comprehensive build and installation tools for it.

Thanks to that, we are able to maintain one codebase for vast majority of the features across all our clients deployments while keeping the option to tailor the pipeline to each individual studio.

### [Avalon-core](https://github.com/pypeclub/avalon-core)

Avalon-core is the heart of OpenPype. It provides the base functionality including key GUIs (albeit expanded and modified by us), database connection, standards for data structures, working with entities and some universal tools.

Avalon is being actively developed and maintained by a community of studios and TDs from around the world, with Pype Club team being an active contributor as well.

Due to the extensive work we've done on OpenPype and the need to react quickly to production needs, we
maintain our own fork of avalon-core, which is kept up to date with upstream changes as much as possible.