1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21 package org.opencastproject.external.endpoint;
22
23 import static org.apache.commons.lang3.StringUtils.isBlank;
24 import static org.apache.commons.lang3.StringUtils.isNoneBlank;
25 import static org.opencastproject.index.service.util.JSONUtils.safeString;
26 import static org.opencastproject.util.RestUtil.getEndpointUrl;
27 import static org.opencastproject.util.doc.rest.RestParameter.Type.BOOLEAN;
28 import static org.opencastproject.util.doc.rest.RestParameter.Type.INTEGER;
29 import static org.opencastproject.util.doc.rest.RestParameter.Type.STRING;
30
31 import org.opencastproject.elasticsearch.index.ElasticsearchIndex;
32 import org.opencastproject.elasticsearch.index.objects.event.Event;
33 import org.opencastproject.external.common.ApiMediaType;
34 import org.opencastproject.external.common.ApiResponseBuilder;
35 import org.opencastproject.external.common.ApiVersion;
36 import org.opencastproject.index.service.api.IndexService;
37 import org.opencastproject.mediapackage.MediaPackage;
38 import org.opencastproject.rest.RestConstants;
39 import org.opencastproject.security.api.UnauthorizedException;
40 import org.opencastproject.systems.OpencastConstants;
41 import org.opencastproject.util.NotFoundException;
42 import org.opencastproject.util.RestUtil;
43 import org.opencastproject.util.UrlSupport;
44 import org.opencastproject.util.data.Tuple;
45 import org.opencastproject.util.doc.rest.RestParameter;
46 import org.opencastproject.util.doc.rest.RestQuery;
47 import org.opencastproject.util.doc.rest.RestResponse;
48 import org.opencastproject.util.doc.rest.RestService;
49 import org.opencastproject.workflow.api.RetryStrategy;
50 import org.opencastproject.workflow.api.WorkflowDefinition;
51 import org.opencastproject.workflow.api.WorkflowInstance;
52 import org.opencastproject.workflow.api.WorkflowOperationInstance;
53 import org.opencastproject.workflow.api.WorkflowService;
54 import org.opencastproject.workflow.api.WorkflowStateException;
55
56 import com.google.gson.JsonArray;
57 import com.google.gson.JsonElement;
58 import com.google.gson.JsonObject;
59 import com.google.gson.JsonPrimitive;
60
61 import org.json.simple.JSONObject;
62 import org.json.simple.parser.JSONParser;
63 import org.json.simple.parser.ParseException;
64 import org.osgi.service.component.ComponentContext;
65 import org.osgi.service.component.annotations.Activate;
66 import org.osgi.service.component.annotations.Component;
67 import org.osgi.service.component.annotations.Reference;
68 import org.osgi.service.jaxrs.whiteboard.propertytypes.JaxrsResource;
69 import org.slf4j.Logger;
70 import org.slf4j.LoggerFactory;
71
72 import java.net.URI;
73 import java.time.ZoneOffset;
74 import java.time.format.DateTimeFormatter;
75 import java.util.HashMap;
76 import java.util.Map;
77 import java.util.Optional;
78
79 import javax.servlet.http.HttpServletResponse;
80 import javax.ws.rs.DELETE;
81 import javax.ws.rs.FormParam;
82 import javax.ws.rs.GET;
83 import javax.ws.rs.HeaderParam;
84 import javax.ws.rs.POST;
85 import javax.ws.rs.PUT;
86 import javax.ws.rs.Path;
87 import javax.ws.rs.PathParam;
88 import javax.ws.rs.Produces;
89 import javax.ws.rs.QueryParam;
90 import javax.ws.rs.core.Response;
91
92 @Path("/api/workflows")
93 @Produces({ ApiMediaType.JSON, ApiMediaType.VERSION_1_1_0, ApiMediaType.VERSION_1_2_0, ApiMediaType.VERSION_1_3_0,
94 ApiMediaType.VERSION_1_4_0, ApiMediaType.VERSION_1_5_0, ApiMediaType.VERSION_1_6_0,
95 ApiMediaType.VERSION_1_7_0, ApiMediaType.VERSION_1_8_0, ApiMediaType.VERSION_1_9_0,
96 ApiMediaType.VERSION_1_10_0, ApiMediaType.VERSION_1_11_0 })
97 @RestService(name = "externalapiworkflowinstances", title = "External API Workflow Instances Service", notes = {},
98 abstractText = "Provides resources and operations related to the workflow instances")
99 @Component(
100 immediate = true,
101 service = WorkflowsEndpoint.class,
102 property = {
103 "service.description=External API - Workflow Instances Endpoint",
104 "opencast.service.type=org.opencastproject.external.workflows.instances",
105 "opencast.service.path=/api/workflows"
106 }
107 )
108 @JaxrsResource
109 public class WorkflowsEndpoint {
110
111 private static final Logger logger = LoggerFactory.getLogger(WorkflowsEndpoint.class);
112
113
114 protected String endpointBaseUrl;
115
116
117 private WorkflowService workflowService;
118 private ElasticsearchIndex elasticsearchIndex;
119 private IndexService indexService;
120
121
122 @Reference
123 public void setWorkflowService(WorkflowService workflowService) {
124 this.workflowService = workflowService;
125 }
126
127
128 @Reference
129 public void setElasticsearchIndex(ElasticsearchIndex elasticsearchIndex) {
130 this.elasticsearchIndex = elasticsearchIndex;
131 }
132
133
134 @Reference
135 public void setIndexService(IndexService indexService) {
136 this.indexService = indexService;
137 }
138
139
140
141
142 @Activate
143 void activate(ComponentContext cc) {
144 logger.info("Activating External API - Workflow Instances Endpoint");
145
146 final Tuple<String, String> endpointUrl = getEndpointUrl(cc, OpencastConstants.EXTERNAL_API_URL_ORG_PROPERTY,
147 RestConstants.SERVICE_PATH_PROPERTY);
148 endpointBaseUrl = UrlSupport.concat(endpointUrl.getA(), endpointUrl.getB());
149 logger.debug("Configured service endpoint is {}", endpointBaseUrl);
150 }
151
152 @POST
153 @Path("")
154 @RestQuery(name = "createworkflowinstance", description = "Creates a workflow instance.", returnDescription = "", restParameters = {
155 @RestParameter(name = "event_identifier", description = "The event identifier this workflow should run against", isRequired = true, type = STRING),
156 @RestParameter(name = "workflow_definition_identifier", description = "The identifier of the workflow definition to use", isRequired = true, type = STRING),
157 @RestParameter(name = "configuration", description = "The optional configuration for this workflow", isRequired = false, type = STRING),
158 @RestParameter(name = "withoperations", description = "Whether the workflow operations should be included in the response", isRequired = false, type = BOOLEAN),
159 @RestParameter(name = "withconfiguration", description = "Whether the workflow configuration should be included in the response", isRequired = false, type = BOOLEAN), }, responses = {
160 @RestResponse(description = "A new workflow is created and its identifier is returned in the Location header.", responseCode = HttpServletResponse.SC_CREATED),
161 @RestResponse(description = "The request is invalid or inconsistent.", responseCode = HttpServletResponse.SC_BAD_REQUEST),
162 @RestResponse(description = "The event or workflow definition could not be found.", responseCode = HttpServletResponse.SC_NOT_FOUND) })
163 public Response createWorkflowInstance(@HeaderParam("Accept") String acceptHeader,
164 @FormParam("event_identifier") String eventId,
165 @FormParam("workflow_definition_identifier") String workflowDefinitionIdentifier,
166 @FormParam("configuration") String configuration, @QueryParam("withoperations") boolean withOperations,
167 @QueryParam("withconfiguration") boolean withConfiguration) {
168 if (isBlank(eventId)) {
169 return RestUtil.R.badRequest("Required parameter 'event_identifier' is missing or invalid");
170 }
171
172 if (isBlank(workflowDefinitionIdentifier)) {
173 return RestUtil.R.badRequest("Required parameter 'workflow_definition_identifier' is missing or invalid");
174 }
175
176 try {
177
178 Optional<Event> event = indexService.getEvent(eventId, elasticsearchIndex);
179 if (event.isEmpty()) {
180 return ApiResponseBuilder.notFound("Cannot find an event with id '%s'.", eventId);
181 }
182 MediaPackage mp = indexService.getEventMediapackage(event.get());
183
184
185 WorkflowDefinition wd;
186 try {
187 wd = workflowService.getWorkflowDefinitionById(workflowDefinitionIdentifier);
188 } catch (NotFoundException e) {
189 return ApiResponseBuilder.notFound("Cannot find a workflow definition with id '%s'.", workflowDefinitionIdentifier);
190 }
191
192
193 Map<String, String> properties = new HashMap<>();
194 if (isNoneBlank(configuration)) {
195 JSONParser parser = new JSONParser();
196 try {
197 properties.putAll((JSONObject) parser.parse(configuration));
198 } catch (ParseException e) {
199 return RestUtil.R.badRequest("Passed parameter 'configuration' is invalid JSON.");
200 }
201 }
202
203
204 WorkflowInstance wi = workflowService.start(wd, mp, null, properties);
205 return ApiResponseBuilder.Json.created(acceptHeader, URI.create(getWorkflowUrl(wi.getId())),
206 workflowInstanceToJSON(wi, withOperations, withConfiguration));
207 } catch (IllegalStateException e) {
208 final ApiVersion requestedVersion = ApiMediaType.parse(acceptHeader).getVersion();
209 JsonObject json = new JsonObject();
210 json.addProperty("message", safeString(e.getMessage()));
211 return ApiResponseBuilder.Json.conflict(requestedVersion, json);
212 } catch (Exception e) {
213 logger.error("Could not create workflow instances", e);
214 return ApiResponseBuilder.serverError("Could not create workflow instances, reason: '%s'", e.getMessage());
215 }
216 }
217
218 @GET
219 @Path("{workflowInstanceId}")
220 @RestQuery(name = "getworkflowinstance", description = "Returns a single workflow instance.", returnDescription = "", pathParameters = {
221 @RestParameter(name = "workflowInstanceId", description = "The workflow instance id", isRequired = true, type = INTEGER) }, restParameters = {
222 @RestParameter(name = "withoperations", description = "Whether the workflow operations should be included in the response", isRequired = false, type = BOOLEAN),
223 @RestParameter(name = "withconfiguration", description = "Whether the workflow configuration should be included in the response", isRequired = false, type = BOOLEAN) }, responses = {
224 @RestResponse(description = "The workflow instance is returned.", responseCode = HttpServletResponse.SC_OK),
225 @RestResponse(description = "The user doesn't have the rights to make this request.", responseCode = HttpServletResponse.SC_FORBIDDEN),
226 @RestResponse(description = "The specified workflow instance does not exist.", responseCode = HttpServletResponse.SC_NOT_FOUND) })
227 public Response getWorkflowInstance(@HeaderParam("Accept") String acceptHeader,
228 @PathParam("workflowInstanceId") Long id, @QueryParam("withoperations") boolean withOperations,
229 @QueryParam("withconfiguration") boolean withConfiguration) {
230 WorkflowInstance wi;
231 try {
232 wi = workflowService.getWorkflowById(id);
233 } catch (NotFoundException e) {
234 return ApiResponseBuilder.notFound("Cannot find workflow instance with id '%d'.", id);
235 } catch (UnauthorizedException e) {
236 return Response.status(Response.Status.FORBIDDEN).build();
237 } catch (Exception e) {
238 logger.error("The workflow service was not able to get the workflow instance", e);
239 return ApiResponseBuilder.serverError("Could not retrieve workflow instance, reason: '%s'", e.getMessage());
240 }
241
242 return ApiResponseBuilder.Json.ok(acceptHeader, workflowInstanceToJSON(wi, withOperations, withConfiguration));
243 }
244
245 @PUT
246 @Path("{workflowInstanceId}")
247 @RestQuery(name = "updateworkflowinstance", description = "Creates a workflow instance.", returnDescription = "", pathParameters = {
248 @RestParameter(name = "workflowInstanceId", description = "The workflow instance id", isRequired = true, type = INTEGER) }, restParameters = {
249 @RestParameter(name = "configuration", description = "The optional configuration for this workflow", isRequired = false, type = STRING),
250 @RestParameter(name = "state", description = "The optional state transition for this workflow", isRequired = false, type = STRING),
251 @RestParameter(name = "withoperations", description = "Whether the workflow operations should be included in the response", isRequired = false, type = BOOLEAN),
252 @RestParameter(name = "withconfiguration", description = "Whether the workflow configuration should be included in the response", isRequired = false, type = BOOLEAN), }, responses = {
253 @RestResponse(description = "The workflow instance is updated.", responseCode = HttpServletResponse.SC_OK),
254 @RestResponse(description = "The request is invalid or inconsistent.", responseCode = HttpServletResponse.SC_BAD_REQUEST),
255 @RestResponse(description = "The user doesn't have the rights to make this request.", responseCode = HttpServletResponse.SC_FORBIDDEN),
256 @RestResponse(description = "The workflow instance could not be found.", responseCode = HttpServletResponse.SC_NOT_FOUND),
257 @RestResponse(description = "The workflow instance cannot transition to this state.", responseCode = HttpServletResponse.SC_CONFLICT) })
258 public Response updateWorkflowInstance(@HeaderParam("Accept") String acceptHeader,
259 @PathParam("workflowInstanceId") Long id, @FormParam("configuration") String configuration,
260 @FormParam("state") String stateStr, @QueryParam("withoperations") boolean withOperations,
261 @QueryParam("withconfiguration") boolean withConfiguration) {
262 try {
263 boolean changed = false;
264 WorkflowInstance wi = workflowService.getWorkflowById(id);
265
266
267 if (isNoneBlank(configuration)) {
268 JSONParser parser = new JSONParser();
269 try {
270 Map<String, String> properties = new HashMap<>((JSONObject) parser.parse(configuration));
271
272
273 wi.getConfigurationKeys().forEach(wi::removeConfiguration);
274
275 properties.forEach(wi::setConfiguration);
276
277 changed = true;
278 } catch (ParseException e) {
279 return RestUtil.R.badRequest("Passed parameter 'configuration' is invalid JSON.");
280 }
281 }
282
283
284
285 if (changed) {
286 workflowService.update(wi);
287 }
288
289
290 if (isNoneBlank(stateStr)) {
291 WorkflowInstance.WorkflowState state;
292 try {
293 state = jsonToEnum(WorkflowInstance.WorkflowState.class, stateStr);
294 } catch (IllegalArgumentException e) {
295 return RestUtil.R.badRequest(String.format("Invalid workflow state '%s'", stateStr));
296 }
297
298 WorkflowInstance.WorkflowState currentState = wi.getState();
299 if (state != currentState) {
300
301
302
303
304
305
306
307
308
309 switch (state) {
310 case PAUSED:
311 workflowService.suspend(wi.getId());
312 break;
313 case STOPPED:
314 workflowService.stop(wi.getId());
315 break;
316 case RUNNING:
317 if (currentState == WorkflowInstance.WorkflowState.INSTANTIATED
318 || currentState == WorkflowInstance.WorkflowState.PAUSED) {
319 workflowService.resume(wi.getId());
320 } else {
321 return RestUtil.R.conflict(
322 String.format("Cannot resume from workflow state '%s'", currentState.toString().toLowerCase()));
323 }
324 break;
325 default:
326 return RestUtil.R.conflict(
327 String.format("Cannot transition state from '%s' to '%s'", currentState.toString().toLowerCase(),
328 stateStr));
329 }
330 }
331 }
332
333 wi = workflowService.getWorkflowById(id);
334 return ApiResponseBuilder.Json.ok(acceptHeader, workflowInstanceToJSON(wi, withOperations, withConfiguration));
335 } catch (NotFoundException e) {
336 return ApiResponseBuilder.notFound("Cannot find workflow instance with id '%d'.", id);
337 } catch (UnauthorizedException e) {
338 return Response.status(Response.Status.FORBIDDEN).build();
339 } catch (Exception e) {
340 logger.error("The workflow service was not able to get the workflow instance", e);
341 return ApiResponseBuilder.serverError("Could not retrieve workflow instance, reason: '%s'", e.getMessage());
342 }
343 }
344
345 @DELETE
346 @Path("{workflowInstanceId}")
347 @RestQuery(name = "deleteworkflowinstance", description = "Deletes a workflow instance.", returnDescription = "", pathParameters = {
348 @RestParameter(name = "workflowInstanceId", description = "The workflow instance id", isRequired = true, type = INTEGER) }, responses = {
349 @RestResponse(description = "The workflow instance has been deleted.", responseCode = HttpServletResponse.SC_NO_CONTENT),
350 @RestResponse(description = "The user doesn't have the rights to make this request.", responseCode = HttpServletResponse.SC_FORBIDDEN),
351 @RestResponse(description = "The specified workflow instance does not exist.", responseCode = HttpServletResponse.SC_NOT_FOUND),
352 @RestResponse(description = "The workflow instance cannot be deleted in this state.", responseCode = HttpServletResponse.SC_CONFLICT) })
353 public Response deleteWorkflowInstance(@HeaderParam("Accept") String acceptHeader,
354 @PathParam("workflowInstanceId") Long id) {
355 try {
356 workflowService.remove(id);
357 } catch (WorkflowStateException e) {
358 return RestUtil.R.conflict("Cannot delete workflow instance in this workflow state");
359 } catch (NotFoundException e) {
360 return ApiResponseBuilder.notFound("Cannot find workflow instance with id '%d'.", id);
361 } catch (UnauthorizedException e) {
362 return Response.status(Response.Status.FORBIDDEN).build();
363 } catch (Exception e) {
364 logger.error("Could not delete workflow instances", e);
365 return ApiResponseBuilder.serverError("Could not delete workflow instances, reason: '%s'", e.getMessage());
366 }
367
368 return Response.noContent().build();
369 }
370
371 private JsonObject workflowInstanceToJSON(WorkflowInstance wi, boolean withOperations, boolean withConfiguration) {
372 JsonObject json = new JsonObject();
373
374 json.addProperty("identifier", wi.getId());
375 json.addProperty("title", safeString(wi.getTitle()));
376 json.addProperty("description", safeString(wi.getDescription()));
377 json.addProperty("workflow_definition_identifier", safeString(wi.getTemplate()));
378 json.addProperty("event_identifier", wi.getMediaPackage().getIdentifier().toString());
379 json.addProperty("creator", wi.getCreatorName());
380 json.add("state", enumToJSON(wi.getState()));
381 if (withOperations) {
382 JsonArray operationsArray = new JsonArray();
383 for (WorkflowOperationInstance op : wi.getOperations()) {
384 operationsArray.add(workflowOperationInstanceToJSON(op));
385 }
386 json.add("operations", operationsArray);
387 }
388
389 if (withConfiguration) {
390 JsonObject configObject = new JsonObject();
391 for (String key : wi.getConfigurationKeys()) {
392 String value = wi.getConfiguration(key);
393 configObject.addProperty(key, value);
394 }
395 json.add("configuration", configObject);
396 }
397
398 return json;
399 }
400
401 private JsonObject workflowOperationInstanceToJSON(WorkflowOperationInstance woi) {
402 JsonObject json = new JsonObject();
403 DateTimeFormatter dateFormatter = DateTimeFormatter.ISO_DATE_TIME.withZone(ZoneOffset.UTC);
404
405 json.addProperty("identifier", woi.getId());
406 json.addProperty("operation", woi.getTemplate());
407 json.addProperty("description", safeString(woi.getDescription()));
408 json.add("state", enumToJSON(woi.getState()));
409 Long timeInQueue = woi.getTimeInQueue();
410 json.addProperty("time_in_queue", timeInQueue != null ? timeInQueue : 0);
411 json.addProperty("host", safeString(woi.getExecutionHost()));
412 json.addProperty("if", safeString(woi.getExecutionCondition()));
413 json.addProperty("fail_workflow_on_error", woi.isFailOnError());
414 json.addProperty("error_handler_workflow", safeString(woi.getExceptionHandlingWorkflow()));
415 json.addProperty("retry_strategy", safeString(new RetryStrategy.Adapter().marshal(woi.getRetryStrategy())));
416 json.addProperty("max_attempts", woi.getMaxAttempts());
417 json.addProperty("failed_attempts", woi.getFailedAttempts());
418 JsonObject config = new JsonObject();
419 for (String key : woi.getConfigurationKeys()) {
420 config.addProperty(key, woi.getConfiguration(key));
421 }
422 json.add("configuration", config);
423
424 if (woi.getDateStarted() != null) {
425 json.addProperty("start", dateFormatter.format(woi.getDateStarted().toInstant().atZone(ZoneOffset.UTC)));
426 } else {
427 json.addProperty("start", "");
428 }
429
430 if (woi.getDateCompleted() != null) {
431 json.addProperty("completion", dateFormatter.format(woi.getDateCompleted().toInstant().atZone(ZoneOffset.UTC)));
432 } else {
433 json.addProperty("completion", "");
434 }
435
436 return json;
437 }
438
439 private JsonElement enumToJSON(Enum<?> e) {
440 return e == null ? null : new JsonPrimitive(e.toString().toLowerCase());
441 }
442
443 private <T extends Enum<T>> T jsonToEnum(Class<T> enumType, String name) {
444 return Enum.valueOf(enumType, name.toUpperCase());
445 }
446
447 private String getWorkflowUrl(long workflowInstanceId) {
448 return UrlSupport.concat(endpointBaseUrl, Long.toString(workflowInstanceId));
449 }
450 }