Mover objetos entre entornos Workfront mediante la API de promoción de entorno Workfront
La capacidad Promoción de entornos permite mover objetos relacionados con la configuración de un entorno a otro. Puede mover estos objetos mediante la API de Workfront como se describe en este artículo.
Para obtener instrucciones sobre cómo mover objetos entre entornos mediante la aplicación de Workfront, consulte:
Requisitos de acceso
Debe tener lo siguiente:
Para obtener más información sobre esta tabla, consulte Requisitos de acceso en la documentación de Workfront.
Requisitos previos
El punto final Crear paquete promocional supone que ya ha configurado el entorno de origen. Esta llamada de API requiere la creación manual de un mapa de objetos de Workfront objCodes y GUID de objetos. A continuación se describe la estructura específica de este mapa.
Objetos compatibles para la promoción del entorno
La función Promoción de entornos está diseñada para proporcionar la capacidad de mover objetos relacionados con la configuración de un entorno a otro. No admite la capacidad de mover objetos transaccionales (con excepciones limitadas).
Para obtener una lista de objetos promocionales y sus subobjetos promocionales incluidos, consulte Objetos admitidos para la promoción de entornos en el artículo Información general sobre cómo mover objetos entre entornos de Workfront.
Autenticación
La API autentica cada solicitud para garantizar que el cliente tenga acceso para ver o modificar un objeto solicitado.
La autenticación se realiza pasando un ID de sesión o una clave de API, que se pueden proporcionar mediante el siguiente método:
Autenticación de encabezado de solicitud
El método de autenticación preferido es pasar un encabezado de solicitud denominado SessionID que contenga el token de sesión. Esto tiene la ventaja de estar a salvo de ataques de falsificación de solicitudes entre sitios (CSRF) y de no interferir con el URI con fines de almacenamiento en caché.
A continuación se muestra un ejemplo de encabezado de solicitud:
GET /attask/api/v15.0/project/search
SessionID: abc1234
Extremos de API
- Creación de un paquete
- Obtener una lista de paquetes
- Obtención de un paquete por ID
- Actualización de propiedades específicas de un paquete
- Eliminación de un paquete
- Ejecutar una ejecución previa
- Ejecutar una instalación
- Obtener una lista de instalaciones para un paquete específico
- Obtener los detalles de instalación de una instalación
Creación de un paquete
Esta llamada ejecuta un proceso de varios pasos.
El primer paso resulta en la creación de un paquete de promoción vacío con el estado "ENSAMBLANDO".
El segundo paso utiliza la matriz objectCollections
proporcionada en el cuerpo del POST para ensamblar los registros solicitados de Workfront. Este paso puede tardar varios minutos en completarse, según la cantidad de registros solicitados y la configuración de Workfront. Al final de este proceso, el paquete de promoción vacío se actualiza con packageEntities
y el estado se establece automáticamente como "BORRADOR".
objectCollections
.objCode
que corresponde al código de objeto documentado en el Explorador de API de Workfront.entities
. Se espera el campo ID
. También puede aceptar un atributo opcional name
para que sea más fácil saber qué representa ID
.objectCollections
, vea la sección Objetos admitidos para la promoción del entorno en este artículo.URL
POST https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/packages
Encabezados
{
"apikey": "**********",
"Content-Type": "application/json"
}
O
{
"sessionID": "*****************",
"Content-Type": "application/json"
}
Cuerpo
{
"name": "Agency Onboarding - 2023-06-06",
"description": "This promotion package contains configuration to support the agency onboarding processes...",
"source": "https://{domain}.{environment}.workfront.com",
"objectCollections": [
{
"objCode": "PROJ",
"entities": [
{
"ID": "6419b8b9001151ee258921a4f7597ba1",
"name": "Agency Request"
}
]
},
{
"objCode": "TMPL",
"entities": [
{
"ID": "6419b8b9001151ee258921a4f7597bb2",
"name": "New Agency Onboarding"
},
{
"ID": "6419b8b9001151ee258921a4f7597bc3",
"name": "New Agency Offboarding"
}
]
},
{
"objCode": "PTLTAB",
"entities": [
{
"ID": "645e6435000b4aaebe4776f4a42ed5ad",
"name": "Agency Performance and Readiness"
}
]
}
]
}
Respuesta
200
{
"data": {
"id": "1d5693b9-b7b5-492d-8219-c21f34bcaca6",
"name": "Agency Onboarding - 2023-06-06",
"description": "This promotion package contains configuration to support the agency onboarding processes...",
"source": "https://{domain}.{environment}.workfront.com",
"status": "ASSEMBLING",
"version": 1,
"createdAt": "2023-06-06T17:29:21.600Z",
"createdById": "61aa9d0e0005fcee8f212835bdaa2619",
"publishedAt": null,
"customerId": "61aa9d090005fa42152c1cb66659f38d"
}
}
Obtener una lista de paquetes
Esta llamada devuelve una lista sin filtrar de paquetes promocionales que pertenecen al cliente.
La respuesta incluirá todos los paquetes creados a partir de cualquiera de las instancias de zona protegida, vista previa o producción del cliente de Workfront.
URL
GET https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/packages
Encabezados
{
"apikey": "**********"
}
O
{
"sessionID": "*****************"
}
Cuerpo
Vacío
Respuesta
200
{
"data": [
{
"id": "1d5693b9-b7b5-492d-8219-c21f34bcaca6",
"name": "Agency Onboarding - 2023-06-06",
"description": "This promotion package contains configuration to support the agency onboarding processes...",
"status": "ASSEMBLING",
"createdAt": "2023-06-06T17:29:21.600Z",
"deletedAt": null
},
{...}
]
}
<!—Comprobar el "estado" anterior—¿se añadió?—>
Obtención de un paquete por ID
Esta llamada devuelve como detalles un paquete promocional solicitado.
La solicitud se puede realizar a través de cualquier entorno independientemente de la fuente original del paquete de promoción.
URL
GET https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/packages/{id}
Encabezados
{
"apikey": "**********"
}
O
{
"sessionID": "*****************"
}
Cuerpo
Vacío
Respuesta
200
{
"data": {
"id": "1d5693b9-b7b5-492d-8219-c21f34bcaca6",
"name": "Agency Onboarding - 2023-06-06",
"description": "This promotion package contains configuration to support the agency onboarding processes...",
"source": "https://{domain}.{environment}.workfront.com",
"status": "DRAFT",
"version": 1,
"createdAt": "2023-06-06T17:29:21.600Z",
"publishedAt": null,
"customerId": "61aa9d090005fa42152c1cb66659f38d",
"packageEntities": {
"GROUP": [
{
"id": "52aa9d0e0005fcee8f212835bdaa2691",
"name": "Default Group",
"description": "null"
- or -
"description": "..."
}
],
"ROLE": [
{...}
],
...
}
}
}
Actualización de propiedades específicas de un paquete
Esta llamada actualiza cualquiera de los contenidos del paquete promocional que se proporcionan en el cuerpo del PATCH.
Los atributos editables son:
- nombre (cadena)
- description (cadena)
- estado (cadena con validación de valor)
Para obtener una descripción detallada de los estados disponibles, consulte Estados de promoción del entorno en el artículo Información general sobre cómo mover objetos entre entornos de Workfront.
URL
PATCH https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/packages/{id}
Encabezados
{
"apikey": "**********",
"Content-Type": "application/json"
}
O
{
"sessionID": "*****************",
"Content-Type": "application/json"
}
Cuerpo
{
"status": "ACTIVE"
}
Respuesta
200
{
"data": {
"id": "1d5693b9-b7b5-492d-8219-c21f34bcaca6",
"name": "Agency Onboarding - 2023-06-06",
"description": "This promotion package contains configuration to support the agency onboarding processes...",
"source": "https://{domain}.{environment}.workfront.com",
"status": "ACTIVE",
"version": 1,
"createdAt": "2023-06-06T17:29:21.600Z",
"publishedAt": "2023-06-06T19:39:01.600Z",
"customerId": "61aa9d090005fa42152c1cb66659f38d",
"packageEntities": {
"GROUP": [
{
"id": "52aa9d0e0005fcee8f212835bdaa2691",
"name": "Default Group",
"description": "..."
}
],
"ROLE": [
{...}
],
...
}
}
}
Eliminación de un paquete
Esta llamada elimina el registro del paquete de promoción. Esta acción no se puede deshacer.
URL
DELETE https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/packages/{id}
Encabezados
{
"apikey": "**********"
}
O
{
"sessionID": "*****************"
}
Cuerpo
Vacío
Respuesta
200
Deleted
Ejecutar una ejecución previa
Esta llamada realiza una comparación entre la definición del paquete y el entorno de destino identificado en la dirección URL.
El resultado es un cuerpo JSON que identifica si un objeto de promoción se encuentra o no en el entorno de destino.
Para cada objeto de promoción, se establecerá uno de los actions
siguientes:
Actualmente no se admite UPDATE action
en las capacidades alfa de este servicio. La opción de permitir una ACTUALIZACIÓN action
es algo que estamos investigando.
URL
POST https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/packages/:id/prepare-installation
Encabezados
{
"apikey": "**********",
"Content-Type": "application/json"
}
O
{
"sessionID": "*****************",
"Content-Type": "application/json"
}
Cuerpo
{}
Respuesta
200
{
"environmentPromotionPackageId": "45f2ae94-76c0-4b13-8f3b-f688de83043d",
"environmentPromotionPackageVersion": 1,
"id": "c0bc79bd-c9c1-4b5b-b118-b1241392de0e",
"userId": "5ba38da500b752fd66439d4f6a9999a1",
"customerId": "5ba38d9d00b74f0c7a38b1b487fc9710",
"status": "PREPARING",
"environment": "mmi.my.workfront.com",
"registeredAt": "2023-10-19T20:00:16.697Z",
"updatedAt": "2023-10-19T20:00:16.701Z",
"translationMap": {
"CTGY": {
"62d9c9a0000013aeeefe7242a0a5fdb2": {
"name": "Example Document Form",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d9c9a0000013aeeefe7242a0a5fdb2"
}
},
"PGRP": {
"62d1eee4001c6618e6b9f9a588ba1598": {
"name": "Asset Detail",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d1eee4001c6618e6b9f9a588ba1598"
}
},
"GROUP": {
"5ba38da500b752b0f46d13186030b7ad": {
"name": "Default Group",
"action": "USEEXISTING",
"isValid": true,
"targetId": "5ba38da500b752b0f46d13186030b7ad"
}
},
"PARAM": {
"62d1eee400f8578895166ee91a83f97a": {
"name": "Asset Type",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d1eee400f8578895166ee91a83f97a"
},
"62d1eee50001407c713514a8970b58e4": {
"name": "Keywords",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d1eee50001407c713514a8970b58e4"
},
"62d1eee5000333ac3981ea4f3df6d88e": {
"name": "Permitted Uses",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d1eee5000333ac3981ea4f3df6d88e"
},
"62d1eee5000b188e9ec8039a097fc7ab": {
"name": "File Format",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d1eee5000b188e9ec8039a097fc7ab"
},
"62d1eee500100c159fd5f838ce560507": {
"name": "CTA",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d1eee500100c159fd5f838ce560507"
},
"62d9c988001c1f23954dbb9d646335b5": {
"name": "Other CTA",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d9c988001c1f23954dbb9d646335b5"
},
"62d9c9880070f546cf4c798ea6c3eaa4": {
"name": "Other Audience",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d9c9880070f546cf4c798ea6c3eaa4"
},
"62d9c990006258baf1b40f2569c3eab7": {
"name": "Target Audience",
"action": "USEEXISTING",
"isValid": true,
"targetId": "62d9c990006258baf1b40f2569c3eab7"
}
}
}
}
id
. En este ejemplo, el campo id
es el tercero desde arriba y tiene un valor que comienza por c0bc79bd
.Ejecutar una instalación
Esta llamada inicia un intento de instalación de un paquete promocional en el entorno de destino identificado en la dirección URL del POST.
URL
POST https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/installations/{id}/install
Encabezados
{
"apikey": "**********",
"Content-Type": "application/json"
}
O
{
"sessionID": "*****************",
"Content-Type": "application/json"
}
Cuerpo
{
}
Respuesta
202
{}
Obtener una lista de instalaciones para un paquete específico
Los resultados incluyen eventos de instalación de todos los entornos en los que se ha implementado el paquete. No se limitan a las instalaciones para el entorno a través de las cuales se realiza la solicitud. Esto le permite identificar qué entornos han recibido este paquete.
URL
GET https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/installations?environmentPromotionPackageId={environmentPromotionPackageId}
Encabezados
{
"apikey": "**********"
}
O
{
"sessionID": "*****************"
}
Cuerpo
Vacío
Respuesta
200
[
{
"id": "2892b936-e09e-455a-935f-e1462ab9753c",
"environmentPromotionPackageId": "4fae2b9d-d315-45f4-909f-a0c0d79fc65d",
"environmentPromotionPackageVersion": 1,
"userId": "8fbbc5bcf4f94a5b862483ee05573e73",
"customerId": "54286d78b064451096752b99bf968481",
"status": "INSTALLED",
"environment": "https://{domain}.{environment}.workfront.com",
"registeredAt": "2021-03-16T02:21:31.908Z",
"updatedAt": null,
"translationMap": {
"ROLE": {
"5f6d114f006883209828ddd9088e63b3": {
"name": "DAM Curator",
"action": "USEEXISTING",
"isValid": true,
"targetId": "600f4bed00028a718599f29575840053"
},
"ad535a9ebe647361e053a7656a0a1575": {
"name": "Copywriter",
"action": "USEEXISTING",
"isValid": true,
"targetId": "600f162700001ca051081c06667b14a4"
},
...
},
"TMPL": {
"5f9b317c00b3db5af69abcd1ed5f82aa": {
"name": "Digital Asset Production (Integrated)",
"action": "CREATE",
"isValid": true,
"targetId": "6054cda40000d5af63dc811d9c2b3a07"
},
...
},
...
}
},
{...}
]
Obtener los detalles de instalación de una instalación
Esta llamada devolverá el translationMap
final producido por el servicio de instalación para una instalación específica.
Cada registro indicará cuál fue el action
prescrito y si la acción se realizó correctamente o no.
Para los registros con CREATE action
, el campo targetId
se establecerá con el valor del registro recién creado en el sistema de destino. Además, el campo installationStatus
se establecerá en INSTALADO.
Para los registros con USEEXISTING action
, el campo targetId
también se establecerá y el campo installationStatus
se establecerá en REGISTERED. Esto significa que el proceso de asignación se ha completado y el servicio de instalación reconoce que ha evaluado el registro y que no hay nada en lo que actuar.
Si el registro tiene un objeto CREATE action
pero no consigue crear el registro correctamente, installationStatus
se establecerá en FAILED y también se proporcionará el motivo del error.
URL
GET https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/installations/{id}
Encabezados
{
"apikey": "**********"
}
O
{
"sessionID": "*****************"
}
Cuerpo
Vacío
Respuesta
200
{
"id": "2892b936-e09e-455a-935f-e1462ab9753c",
"environmentPromotionPackageId": "4fae2b9d-d315-45f4-909f-a0c0d79fc65d",
"environmentPromotionPackageVersion": 1,
"userId": "8fbbc5bcf4f94a5b862483ee05573e73",
"customerId": "54286d78b064451096752b99bf968481",
"status": "INSTALLED",
"environment": "https://{domain}.{environment}.workfront.com",
"registeredAt": "2021-03-16T02:21:31.908Z",
"updatedAt": null,
"translationMap": {
"ROLE": {
"5f6d114f006883209828ddd9088e63b3": {
"name": "DAM Curator",
"action": "USEEXISTING",
"isValid": true,
"targetId": "600f4bed00028a718599f29575840053"
},
...
},
"TMPL": {
"5f9b317c00b3db5af69abcd1ed5f82aa": {
"name": "Digital Asset Production (Integrated)",
"action": "CREATE",
"isValid": true,
"targetId": "6054cda40000d5af63dc811d9c2b3a07"
},
...
},
...
}
}
Sobrescritura
Este es un proceso de tres pasos.
- Crear un mapa de traducción (esto es análogo a la fase de "preparación de la instalación").
- Edite la asignación de traducción generada, estableciendo los campos
action
ytargetId
para cualquier objeto que desee sobrescribir. La acción debe serOVERWRITING
ytargetId
debe ser el uuid del objeto que debe sobrescribirse - Ejecute la instalación.
Paso 1 - Crear un mapa de traducción
URL
POST https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/packages/{id}/translation-map
Cuerpo
Ninguno
Respuesta
Un mapa de traducción, con un estado 202 - OK
{
{objcode}: {
{object uuid}: {
"targetId": {uuid of object in destination},
"action": {installation action},
"name": {name of the object},
"isValid": true
},
{...more objects}
},
{...more objcodes}
}
Ejemplo
{
"UIVW": {
"109f611680bb3a2b0c0a8c1f5ec63f6d": {
"targetId": "6643a26b0001401ff797ccb318f97aa6",
"action": "CREATE",
"name": "Actual Portfolio Cost by Program",
"isValid": true
}
},
"UIGB": {
"edb4c6c127d38910e4860eb25569a5cc": {
"targetId": "6643a26b000178fb5cc27b74cc1e87ec",
"action": "USEEXISTING",
"name": "Actual Portfolio Cost by Program",
"isValid": true
}
},
"UIFT": {
"f97b662e229fd09ee595d8d359ec88bd": {
"targetId": "6643a26b00015cdd6727b76d6fda1d1d",
"action": "USEEXISTING",
"name": "Actual Portfolio Cost by Program",
"isValid": true
}
},
"PTLSEC": {
"4bb80aa88a96420296a7f47bf866f162": {
"targetId": "4bb80aa88a96420296a7f47bf866f162",
"action": "USEEXISTING",
"name": "Actual Portfolio Cost by Program",
"isValid": true
}
},
"EXTSEC": {
"65f8637900015e4dceb6fe079bd5409d": {
"targetId": "65f8637900015e4dceb6fe079bd5409d",
"action": "USEEXISTING",
"name": "Asnyc List",
"isValid": true
}
},
"PTLTAB": {
"65f8638a00016422a83ddc3508852d0f": {
"targetId": "65f8638a00016422a83ddc3508852d0f",
"action": "CREATEWITHALTNAME",
"name": "Cool 2.0 The Best",
"isValid": true
}
}
}
Paso 2: Modificación del mapa de traducción
No hay punto final para este paso.
-
En el mapa de traducción devuelto en Paso 1: Creación de un mapa de traducción, inspeccione la lista de objetos que se instalarán.
-
Actualice el campo de acción de cada objeto a la acción de instalación deseada.
-
Valide
targetId
en cada objeto. Si la acción establecida esUSEEXISTING
oOVERWRITING
,targetId
debe establecerse en el UUID del objeto de destino en el entorno de destino. Para cualquier otra acción, targetId debe ser una cadena vacía.note note NOTE targetId
ya se ha rellenado si se detectó un conflicto.
Paso 3 - Instalar
URL
POST https://{domain}.{environment}.workfront.com/environment-promotion/api/v1/packages/{id}/install
Cuerpo
Este es un objeto con un solo campo translationMap
, que debe coincidir con el mapa de traducción modificado de Paso 2 - Modificar el mapa de traducción.
{
"translationMap": {
{objcode}: {
{object uuid}: {
"targetId": {uuid of object in destination},
"action": {installation action},
"name": {name of the object},
"isValid": true
},
{...more objects}
},
{...more objcodes}
}
}
Ejemplo
{
"translationMap": {
"UIVW": {
"109f611680bb3a2b0c0a8c1f5ec63f6d": {
"targetId": "6643a26b0001401ff797ccb318f97aa6",
"action": "USEEXISTING",
"name": "Actual Portfolio Cost by Program",
"isValid": true
}
},
"UIGB": {
"edb4c6c127d38910e4860eb25569a5cc": {
"targetId": "6643a26b000178fb5cc27b74cc1e87ec",
"action": "USEEXISTING",
"name": "Actual Portfolio Cost by Program",
"isValid": true
}
},
"UIFT": {
"f97b662e229fd09ee595d8d359ec88bd": {
"targetId": "6643a26b00015cdd6727b76d6fda1d1d",
"action": "OVERWRITING",
"name": "Actual Portfolio Cost by Program",
"isValid": true
}
},
"PTLSEC": {
"4bb80aa88a96420296a7f47bf866f162": {
"targetId": "4bb80aa88a96420296a7f47bf866f162",
"action": "USEEXISTING",
"name": "Actual Portfolio Cost by Program",
"isValid": true
}
},
"EXTSEC": {
"65f8637900015e4dceb6fe079bd5409d": {
"targetId": "65f8637900015e4dceb6fe079bd5409d",
"action": "USEEXISTING",
"name": "Asnyc List",
"isValid": true
}
},
"PTLTAB": {
"65f8638a00016422a83ddc3508852d0f": {
"targetId": "65f8638a00016422a83ddc3508852d0f",
"action": "CREATEWITHALTNAME",
"name": "Cool 2.0 The Best",
"isValid": true
}
}
}
}
Respuesta
La respuesta incluye el estado {uuid of the created installation}
y 202 - ACCEPTED
.
Ejemplo: b6aa0af8-3520-4b25-aca3-86793dff44a6